Manage inboxes

After onboarding, you can manage your own organization's inboxes through the API. Use mailbox:read for reads and exports, and mailbox:manage for deletion.

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.

List your inboxes

curl --fail-with-body --silent --show-error \
  "$MAILACTOR_API_URL/v1/inboxes?limit=20" \
  -H "x-api-key: $MAILACTOR_API_KEY"

The response contains inboxes and nextCursor. Results are newest-first. Follow pagination until nextCursor is null when you need a complete inventory.

{
  "inboxes": [
    {
      "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"
    }
  ],
  "nextCursor": null
}

Inspect one inbox

curl --fail-with-body --silent --show-error \
  "$MAILACTOR_API_URL/v1/inboxes/$INBOX_ID" \
  -H "x-api-key: $MAILACTOR_API_KEY"

Success is 200, with the same direct Inbox object shown after creation. It includes the exact address, domain, domainKind, display name, status, and timestamps. The current public API does not provide an inbox rename, address change, or pause/resume endpoint.

Export mailbox content

curl --fail-with-body --silent --show-error \
  "$MAILACTOR_API_URL/v1/inboxes/$INBOX_ID/export?limit=20" \
  -H "x-api-key: $MAILACTOR_API_KEY"

An export page contains formatVersion, inbox, messages, and nextCursor. Save every page. This is a paginated view rather than a point-in-time snapshot; concurrent changes require reconciliation. Attachment metadata is included with messages, not raw MIME or attachment bytes. Store exports securely: they contain message content.

For a complete export example, including inbound and outbound messages, see the export response. Continue until nextCursor: null; a successful first page is not a complete export. The API cannot guarantee an atomic “export everything, then delete” for an active inbox: there is no snapshot or pause endpoint. Stop application sends and coordinate with senders before export, repeat complete passes with message-ID deduplication, and check for new arrivals before deletion. This reduces the race but does not eliminate it. If your task requires guaranteed lossless export, retain the inbox and report that the guarantee is unsupported. Delete only when the task explicitly accepts this limitation.

Download eligible attachments separately before deleting if your backup needs bytes. Quarantined attachments cannot be exported as bytes through the public API.

Delete an inbox

curl --fail-with-body --silent --show-error -X DELETE \
  "$MAILACTOR_API_URL/v1/inboxes/$INBOX_ID" \
  -H "x-api-key: $MAILACTOR_API_KEY"

Successful deletion returns 204. If deletion is pending (409), retry the same DELETE after 1, 2, 4, then at most 5 seconds, up to your deadline. After success or an ambiguous response, confirm that GET for that inbox returns 404. The DELETE call needs mailbox:manage; the confirming GET needs mailbox:read. Use the same organization and a key that could read the inbox before deletion. If confirmation returns 200, deletion is not confirmed: retry DELETE and GET with the same bounded schedule. If access or key restrictions changed, or GET returns 401 / 403, report verification as blocked rather than interpreting invisibility as deletion. At the deadline, retain the inbox ID and report the last observed state.

Mailbox deletion is not immediate erasure of every delivery, abuse, or audit record. Those records have their own retention policy. Whole-organization erasure is currently handled by the team.