Email addresses

An email address (an “inbox” in the API, with ids starting ibx_) belongs to the account. It can be assigned to a device or held unassigned; either way it counts toward the plan.

Choosing a domain

GET /domains lists the domains this account can create addresses on: shared domains its plan reaches, and any domains it brought itself.

{ "domains": [{ "domain": "example-pool.email", "reserved": false, "tier": "free" }] }

reserved is true for a domain that belongs to your account alone. tier is the plan group a shared domain belongs to, and null for one of your own.

Shared domains are grouped by plan, so an account only gets addresses on its own plan’s group and those below it.

Creating an address

POST /inboxes with a client-generated id and a domain:

curl https://api.mailcycle.email/inboxes \
  -H "Authorization: Bearer $MAILCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "ibx_k3v9x2mq7a", "domain": "example-pool.email", "prefix": "receipts" }'

Field	Notes
id	Required. ibx_ followed by 4 to 48 letters and digits. You choose it, so sealed data can be bound to it before the address exists.
domain	Required, unless emailAddress is given. One of the domains from GET /domains.
prefix	Optional. The server adds a random ending: receipts-x7k2@….
style	Optional. With no prefix or localPart, the server rolls a name in this style: person (maya.holt), business (harbor-supply), team (orders_desk) or neutral (quiet.falcon42, the default).
localPart	The exact name before the @. Any name from Scale up. On every plan, a rolled name from GET /inboxes/names.
emailAddress	The whole address, as shorthand for domain plus localPart. Same rules as localPart.
retentionDays	Optional. 1 to 90, default 7.
meta	Optional. The sealed label.
publicKey	The address’s X25519 public key, base64url. Without it the address refuses mail.

The response is the new address as inbox. Past the plan’s limit the request returns 402 allocation_exhausted.

Rolling a name

GET /inboxes/names?style=person&domain=example-pool.email returns up to eight names in that style that are free on the domain:

{ "style": "person", "domain": "example-pool.email", "names": ["maya.holt", "theo.brandt", "…"] }

Pass one as localPart to take it. The names are free when listed, not held, so another account can take one first; creating it then returns 409 address_taken. A name is two words from one style’s word lists joined by ., - or _, sometimes with a number of up to three digits on the end: maya.holt, harbor-supply42, orders_desk_7.

Caution

The public key is derived from your recovery phrase. Each SDK derives and sends it, for example mc.addresses.create() in TypeScript. An address created without publicKey refuses mail until it has one. Opening Mailcycle on the account adds it, and so does PATCH /inboxes/:id with publicKey from a signed-in session. GET /inboxes says which addresses can receive, as receives.

Changing an address

PATCH /inboxes/:id updates the sealed label (meta) or retentionDays, or adds a missing publicKey. A shorter retention applies to mail already stored, and deletes what is past it.

The sealed meta holds the label and the address’s sender name, like “Support at Acme”, which the device or agent holding the address puts on the From line. Set both in the app under Edit address; a sender name needs a plan that sends, Personal and up. Writing meta replaces both, so carry the sender name over when you change the label.

Assigning to a device

POST /workers/:id/inboxes with { "inboxId": "ibx_…" } puts an address on a device, which then receives its mail. DELETE /workers/:id/inboxes/:inboxId takes it off. On Free a device holds one address. Both need a signed-in session, since they decide where an address’s mail goes; an API key gets 403 session_required.

Deleting an address

DELETE /inboxes/:id deletes the address with its mail and attachments and frees its place on the plan. The address is retired and never issued to anyone again, so password resets sent to it cannot reach a stranger.