Mailactor
API reference

Create an inbox

Omit domainId for a managed starter address, or supply a verified customer-domain ID.

Required scope: mailbox:manage.

POST/v1/inboxes

Authorization

tenantApiKey
x-api-key<token>

A scoped tenant key returned once by an operator. Never place it in URLs, logs, prompts, or client-side application code.

In: header

Request Body

application/json

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

# Set the API key and replace resource IDs with your saved IDs.curl --fail-with-body --silent --show-error -X POST \  "https://api.mailactor.com/v1/inboxes" \  -H "x-api-key: $MAILACTOR_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "localPart": "research-agent",  "displayName": "Research Agent"}'

Response examples

Illustrative values; save the IDs and limits returned by your own requests.

HTTP 201

{
  "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"
}

HTTP 409

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