Delivery status

Every outbound send returns a submission ID. Read that submission with delivery:read:

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

Interpret the result

Status	Meaning / next step
`pending`	Stored; delivery work has not finished. Continue polling.
`queued`	Accepted into the delivery queue. Continue polling.
`deferred`	Temporary delivery problem. Continue polling; do not send a duplicate.
`delivered`	The recipient mail server accepted the message.
`partially_delivered`	Recipients have mixed outcomes. Inspect every recipient.
`bounced`	Permanent recipient/server rejection. Inspect the response.
`expired`	Delivery could not be confirmed before the delivery window ended.
`unknown`	The transport outcome is ambiguous. Reconcile before deciding to resend.
`failed`	The operation failed; inspect `failureCode` and `response`.

Inspect the recipients array even when the aggregate status appears final. A mixed submission can contain recipients still in a nonterminal state. Wait until every recipient has a terminal outcome, or stop at your deadline and report the remaining uncertainty. Later transport evidence can refine an expired or unknown result.

delivered is server acceptance, not proof of inbox placement, opening, or reading. Mailactor does not provide read receipts here.

HTTP 200 example

Response: getSubmission 200

{
  "id": "00000000-0000-4000-8000-000000000001",
  "from": {
    "email": "research-agent@inbox.mailactor.com",
    "name": "Research Agent"
  },
  "recipients": [
    {
      "email": "you@example.com",
      "status": "delivered",
      "response": "250 2.0.0 Message accepted",
      "updatedAt": "2026-09-08T12:01:00.000Z"
    }
  ],
  "subject": "Your research update",
  "metadata": {
    "taskId": "research-42"
  },
  "status": "delivered",
  "queueId": "mailactor-example-queue",
  "response": "250 2.0.0 Message accepted",
  "failureCode": null,
  "createdAt": "2026-09-08T12:00:00.000Z",
  "updatedAt": "2026-09-08T12:01:00.000Z"
}

Mixed recipients

For partially_delivered, inspect recipients rather than retrying the entire send:

Recipient state	Action
`pending`, `queued`, `deferred`	Continue polling the same submission.
`delivered`	Report server acceptance for this recipient. Do not send it again.
`bounced`	Report permanent rejection with its `response`.
`expired`, `unknown`	Retain the submission ID and report delivery as unconfirmed; later evidence may refine it.

An aggregate failed is a failed operation; retain failureCode and response. At your deadline, return a per-recipient result including any unresolved states. Any new send after failure is an explicit application decision, not an automatic retry with a fresh key.

Reference-client stopping rule

The optional runtime reference client labels partially_delivered as an aggregate terminal status. Its wait helpers can therefore return while an individual recipient is still deferred. That label does not mean every recipient finished. Inspect the returned recipients; for this guide's per-recipient completion rule, continue GET /v1/submissions/{submissionId} within your deadline whenever any recipient is pending, queued, or deferred.

GET /v1/submissions/{submissionId}/events returns {events: [...]} and has no cursor pagination. Do not pass limit or cursor or expect nextCursor on that operation.

Poll responsibly

Wait 1 second before the first request, then 2, 4, and at most 5 seconds between checks. Honor a longer Retry-After when supplied. Choose a deadline; retain the submission ID when it expires. Do not turn a deferred or unknown outcome into a success message.

GET /v1/submissions/{submissionId}/events provides delivery events. GET /v1/metrics/delivery exposes your organization's delivery metrics. Neither requires access to another tenant's data.

Why a send may be blocked

Sending requires an active organization, an authorized sender domain, sufficient key permissions, and available traffic quota. A recipient may also be suppressed after a hard bounce, complaint, or manual suppression.

An organization-wide managed starter allowance cannot be reset by creating a new inbox. Inspect limits and the error's recovery fields before retrying.