Mailboxes

Returns every mailbox your organization owns. This is usually the first call an integration makes, because every other endpoint takes an address and this is where the valid ones come from.

GET https://app.ruber.me/api/v1/mailboxes

Required permission: Mailboxes → Read (mailboxes:read)

Request

curl https://app.ruber.me/api/v1/mailboxes \
  -H "Authorization: Bearer rk_your_key_here"

const response = await fetch("https://app.ruber.me/api/v1/mailboxes", {
  headers: { Authorization: `Bearer ${process.env.RUBER_API_KEY}` },
});

const { data } = await response.json();

import os, requests

response = requests.get(
    "https://app.ruber.me/api/v1/mailboxes",
    headers={"Authorization": f"Bearer {os.environ['RUBER_API_KEY']}"},
)

data = response.json()["data"]

This endpoint takes no parameters. It returns every mailbox on the organization the key belongs to — there is no pagination, because an organization has tens of mailboxes, not thousands.

Response

{
  "data": [
    {
      "address": "billing@yourdomain.com",
      "display_name": "Billing",
      "mode": "smart",
      "quota_bytes": 10737418240,
      "status": "active",
      "used_bytes": 284119402
    },
    {
      "address": "legal@yourdomain.com",
      "display_name": null,
      "mode": "private",
      "quota_bytes": 10737418240,
      "status": "active",
      "used_bytes": 1048576
    }
  ]
}

array

Every mailbox the organization owns, sorted by address.

Hide properties

string

The full email address, always lowercase. This is the value other endpoints expect.

string | null

The name shown beside the address, or null if none was set.

string

smart, private, or migrating_to_private.Only smart mailboxes can be read or sent from through the API — see Private mailboxes.

string

active, provisioning, or suspended.Mailboxes that are not active are included on purpose, so you can tell “you do not own this” from “you own it and it is not ready” — two very different problems.

integer | null

The mailbox’s storage limit in bytes, or null where no limit is set.

integer

Storage currently used, in bytes.

Both non-active and Private mailboxes are listed. Filtering them out would be worse than including them: an integration would report a mailbox as missing when it exists and is simply unreadable, or not ready yet. mode and status tell you which endpoints will accept it.

Aliases

GET https://app.ruber.me/api/v1/aliases

Required permission: Mailboxes → Read (mailboxes:read) Addresses your organization owns that are not mailboxes in their own right. Mail to an alias is delivered into the mailbox behind it, and you can send as one.

{
  "data": [
    { "address": "support@yourdomain.com", "owner": "team@yourdomain.com" },
    { "address": "hello@yourdomain.com", "owner": "team@yourdomain.com" }
  ]
}

owner is the mailbox the alias delivers into — and the one that files the Sent copy and carries the sending limits when you send as the alias. An integration reasoning about either has to know which mailbox is really behind the address.

Only aliases pointing at a usable Smart mailbox are listed. An alias whose target is Private or suspended is left out rather than listed and then refused everywhere — it is not a usable sending identity, and an address that exists in one endpoint and fails in every other is worse than one that is absent.Aliases are read-only here. Creating one reserves a name on a domain permanently and interacts with role addresses and catch-all, which is a considered decision rather than an API call — it stays in the dashboard.

Errors

Code	HTTP	Cause
`unauthorized`	`401`	Missing, malformed, unknown or revoked key.
`forbidden`	`403`	The key lacks `mailboxes:read`.
`rate_limited`	`429`	Over 600 requests in a minute. See `Retry-After`.
`internal_error`	`500`	The lookup failed on our side. Safe to retry.

A key with no permissions at all — possible only for keys created before permissions existed — authenticates and then fails here with forbidden. The key list in Settings → API keys marks those; revoke and recreate them. See Errors for the full response shape.

Start here

Using Ruber

API

Request

Response

Aliases

Errors

​Request

​Response

​Aliases

​Errors

Request

Response

Aliases

Errors