Inboxes

An inbox is an email address that can receive and send. It lives on your workspace's private mailbay.email domain or on a domain you added.

The inbox object

Field	Type	Description
id	string	Prefixed id, for example `ibx_01jbz8w4k2q9…`. Sorts by creation time.
org_id	string	The organization that owns the inbox.
address	string	The full address: local_part@domain.
local_part	string	The part before the @.
domain	string	Your workspace's code domain, such as `k7m3qz.mailbay.email`, or a custom domain you added.
catch_all	boolean	True for the Catch-all inbox of the code domain (address `*@k7m3qz.mailbay.email`).
display_name	string \| null	Shown as the sender name on outgoing mail.
created_at	string	RFC 3339 timestamp.

{
  "id": "ibx_01jbz8w4k2q9...",
  "org_id": "org_01jbz7t0a1b2...",
  "address": "support@k7m3qz.mailbay.email",
  "local_part": "support",
  "domain": "k7m3qz.mailbay.email",
  "display_name": "Support",
  "created_at": "2026-10-13T09:40:52Z"
}

Your mailbay.email address space

Every workspace gets a random, permanent code of six lowercase letters and digits, such as k7m3qz, and with it a private domain: k7m3qz.mailbay.email. You never pick or rename the code, and nobody can guess it, so addresses under it are yours alone.GET /v1/me returns it as org.shared_code and the full domain as shared_domain.

Any address under your code works. Create named inboxes such as support@k7m3qz.mailbay.email for mail you want kept apart. Everything else, for example signup-test-42@k7m3qz.mailbay.email, reaches your Catch-all inbox in the Playground, which Mailbay creates for you. Messages keep the address they were sent to in delivered_to, so an agent can make up a fresh address per test and wait for it with the to filter. A +tag maps to the inbox without the tag. Mail for a code that does not exist is rejected during the SMTP session.

The Catch-all receives only. To send from an address, create an inbox with that name. Sending from mailbay.email addresses is a sandbox until you verify a domain: see Sending.

Create an inbox

POST/v1/inboxes

Both fields are optional. An empty body creates an inbox with a random name. Send an Idempotency-Key header to make retries safe.

curl -X POST https://api.mailbay.dev/v1/inboxes \
  -H "Authorization: Bearer $MAILBAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c7e2a" \
  -d '{"local_part": "support", "display_name": "Support"}'

mailbay inbox create support --display-name "Support"

List inboxes

GET/v1/inboxes

curl https://api.mailbay.dev/v1/inboxes \
  -H "Authorization: Bearer $MAILBAY_API_KEY"

# {"data": [{"id": "ibx_...", "address": "support@k7m3qz.mailbay.email", ...}]}

Delete an inbox

DELETE/v1/inboxes/{id}

Returns 204 No Content. On a custom domain, mail sent to the address afterwards is rejected during the SMTP session, so senders get an immediate bounce instead of silence. On your mailbay.email domain it lands in the Catch-all instead.

mailbay inbox delete ibx_01jbz8w4k2q9

Limits

The free plan includes 3 inboxes; the Catch-all does not count. Creating a fourth returns inbox_limit_reached with the fix in the response. Mail into one code domain is rate limited to keep the shared domain clean.

Inbox names use 1 to 64 letters, digits, dots, hyphens or underscores. A name that is already taken on the same domain returns inbox_exists.

The inbox object#

Your mailbay.email address space#

Create an inbox#

List inboxes#

Delete an inbox#