Create an inbox

An inbox is an email identity within your organization. It keeps its address and conversations across API requests.

Required scope: mailbox:manage.

Set MAILACTOR_API_URL and MAILACTOR_API_KEY as shown in quickstart. Examples below use illustrative IDs and values; use the values returned for your organization.

Use a managed address

curl --fail-with-body --silent --show-error \
  "$MAILACTOR_API_URL/v1/inboxes" \
  -H "x-api-key: $MAILACTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"research-agent","displayName":"Research Agent"}'

Omit domainId to use the managed domain. Save the returned id and address instead of constructing either yourself. On the production starter domain, the requested local part becomes an address such as research-agent@inbox.mailactor.com.

Request fields

Unknown fields are rejected. Success is 201 Created, returning the inbox directly, without an inbox wrapper. A managed inbox has domainId: null.

{
  "id": "inb_0123456789abcdef01234567",
  "localPart": "research-agent",
  "domainId": null,
  "domainKind": "managed",
  "domain": "inbox.mailactor.com",
  "address": "research-agent@inbox.mailactor.com",
  "displayName": "Research Agent",
  "status": "active",
  "createdAt": "2026-09-08T12:00:00.000Z",
  "updatedAt": "2026-09-08T12:00:00.000Z"
}

Choose a name

Use a lowercase ASCII local part with letters, digits, dots, underscores, or hyphens. It must start and end with a letter or digit, contain no consecutive dots, and be at most 64 characters. Names such as admin, postmaster, abuse, security, support, and noreply are reserved.

Managed addresses share one namespace, so another organization may already own your preferred name. Choose a distinctive name when you receive a conflict. displayName is optional and is limited to 200 characters.

Use your own domain

First register and verify your domain. Then supply its ID:

{
  "localPart": "research-agent",
  "displayName": "Research Agent",
  "domainId": "00000000-0000-4000-8000-000000000001"
}

Replace the example UUID with your registered domain's actual ID. Confirm that the response has domainKind: "customer" and the expected domainId.

Recover from an interrupted request

Inbox creation does not require an idempotency key. Always choose a localPart in automated workflows. If the connection fails, list every inbox page. Match the requested localPart and domainKind: "managed", or the exact domainId for a customer domain; take the exact address from the matching response. Do not infer ownership from a 409: names are shared across organizations. If a complete inventory contains no match, retry the same create input after waits of 1, 2, 4, then at most 5 seconds, honoring a longer Retry-After when present. Choose a deadline, for example 60 seconds for this reconciliation phase; this is an application budget, not an API guarantee. For 409 inbox_address_unavailable, choose a different name as a new creation attempt only after the full inventory contains no match. For 409 inbox_limit_exceeded, stop and resolve your organization's inbox limit; changing the name will not help. If your read permission is missing or the inventory is incomplete, report the result as unresolved.

A key restricted to existing inbox IDs may not be allowed to create new inboxes. The managed starter sending allowance is shared across the organization; creating additional inboxes does not reset it.

Full request and response reference

A shared-name conflict uses this error envelope; branch on error, not the diagnostic message:

{
  "error": "inbox_address_unavailable",
  "message": "The requested inbox address is unavailable"
}