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 }] }

reserved is true for a domain that belongs to your account alone.

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@….
localPart	Scale and up. The exact name before the @. Use instead of prefix.
emailAddress	Scale and up. The whole address, as shorthand for domain plus 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.

Caution

The public key is derived from your recovery phrase, and a script cannot derive it yet. An address created without publicKey refuses mail, and nothing adds the key later. Create receiving addresses in the Mailcycle app, then manage them from your script.

Changing an address

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

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.

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.