List 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.

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

Reference

List mailboxes

Request

Response

Errors

​Request

​Response

​Errors

Request

Response

Errors