Mailactor
API reference

Send a message

Managed addresses have a deployment-configured lifetime starter allowance. Customer-domain inboxes do not use it.

Required scope: mailbox:send.

POST/v1/inboxes/{inboxId}/messages

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

Path Parameters

inboxId*string
Match^inb_[a-f0-9]{24}$

Header Parameters

idempotency-key*string
Match^[A-Za-z0-9._:-]+$
Length8 <= length <= 200

Request Body

application/json

Response Body

application/json

application/json

application/json

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.# Generate once per logical action; preserve this key for retries.export IDEMPOTENCY_KEY="request-$(uuidgen)"curl --fail-with-body --silent --show-error -X POST \  "https://api.mailactor.com/v1/inboxes/$INBOX_ID/messages" \  -H "x-api-key: $MAILACTOR_API_KEY" \  -H "idempotency-key: $IDEMPOTENCY_KEY" \  -H "Content-Type: application/json" \  -d '{  "to": [    {      "email": "you@example.com",      "name": "Alex"    }  ],  "subject": "Your research update",  "text": "The research is ready for your review.",  "html": "<p>The research is ready for your review.</p>",  "replyTo": {    "email": "research-agent@inbox.mailactor.com",    "name": "Research Agent"  },  "metadata": {    "taskId": "research-42"  }}'

Response examples

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

HTTP 202

{
  "message": {
    "id": "msg_1123456789abcdef01234567",
    "inboxId": "inb_0123456789abcdef01234567",
    "threadId": "thr_0123456789abcdef01234567",
    "direction": "outbound",
    "internetMessageId": "<research-42@inbox.mailactor.com>",
    "inReplyTo": null,
    "references": [],
    "from": {
      "email": "research-agent@inbox.mailactor.com",
      "name": "Research Agent"
    },
    "to": [
      {
        "email": "you@example.com",
        "name": "Alex"
      }
    ],
    "subject": "Your research update",
    "text": "The research is ready for your review.",
    "html": "<p>The research is ready for your review.</p>",
    "replyTo": {
      "email": "research-agent@inbox.mailactor.com",
      "name": "Research Agent"
    },
    "metadata": {
      "taskId": "research-42"
    },
    "delivery": {
      "submissionId": "00000000-0000-4000-8000-000000000001",
      "status": "submitted",
      "failureCode": null
    },
    "createdAt": "2026-09-08T12:00:00.000Z",
    "updatedAt": "2026-09-08T12:00:00.000Z"
  },
  "submission": {
    "id": "00000000-0000-4000-8000-000000000001",
    "from": {
      "email": "research-agent@inbox.mailactor.com",
      "name": "Research Agent"
    },
    "recipients": [
      {
        "email": "you@example.com",
        "status": "pending",
        "response": null,
        "updatedAt": "2026-09-08T12:00:00.000Z"
      }
    ],
    "subject": "Your research update",
    "metadata": {
      "taskId": "research-42"
    },
    "status": "pending",
    "queueId": null,
    "response": null,
    "failureCode": null,
    "createdAt": "2026-09-08T12:00:00.000Z",
    "updatedAt": "2026-09-08T12:00:00.000Z"
  },
  "replayed": false
}

HTTP 410

{
  "error": "idempotency_result_expired",
  "message": "The original mailbox result was deleted; this idempotency key cannot be reused"
}