Send, reply, and forward API

All three paths need an Idempotency-Key header and the Send (messages:send) scope.

Send new mail#

POST /v1/messages

curl -sS https://api.atmark.ai/v1/messages \
  -H "Authorization: Bearer $ATMARK_AGENT_TOKEN" \
  -H "Idempotency-Key: 2026-09-27-weekly-report" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "7c21…f5a1",
    "from": "scout@atmark.ai",
    "to": ["partner@example.com"],
    "subject": "Weekly report",
    "text": "Hello, here is this week'"'"'s report."
  }'

Results#

provider_message_id is the delivery ID assigned when the mail goes out. It's null until then.

decision holds the verdict (verdict), an array of reasons (reasons), the policy version (policy_version), when it was evaluated (evaluated_at), and how long to wait (retry_after_seconds).

{
  "status": "sent",
  "message_id": "0f8a…",
  "message_id_header": "<…@atmark.ai>",
  "provider_message_id": "…",
  "decision": {
    "verdict": "allowed",
    "reasons": ["allowlist_match"],
    "policy_version": 3,
    "evaluated_at": "2026-09-27T09:00:00.000Z",
    "retry_after_seconds": null
  }
}

Allowed sends carry reasons too. allowlist_match in the example above means every recipient was on the outbound allowlist. All codes are in Reason codes.

A 403 isn't an outage; it's the policy doing its job. Retrying with the same key returns the same denial. After fixing the cause, or waiting retry_after_seconds, send with a new Idempotency-Key.

Replayed requests#

Repeat the same request with the same Idempotency-Key and no second email goes out; you get the message's current state with replayed: true. The body has status, message_id, message_id_header, and provider_message_id, but no decision, approval_id, or expires_at. Read the decision with GET /v1/audit?message_id=… and the approval with GET /v1/approvals/{id}.

Reply#

POST /v1/threads/{threadId}/reply

threadId is the received email's thread_id.

If the received email doesn't exist, you get 404 message_not_found. Results are the same as for new mail.

Forward#

POST /v1/messages/{messageId}/forward

messageId is the received email's id.

• Only the original body text is carried over. Sending html returns 400. Attachments aren't forwarded; attachments_omitted in the response says how many were left out.
• If the received email's injection_risk is anything other than none, the forward is refused with 422 forward_refused_injection_risk. If the content matters, write a new email in your own words.