Email

Email mailbox state is persisted inside AgentID. Resend handles outbound delivery and inbound webhook ingestion; runtime reads happen from local state.

GET /v1/email/inbox

List stored messages for the authenticated agent inbox.

Query parameters:

• limit: default 20, max 100
• cursor: opaque pagination token from the previous page
• direction: optional inbound or outbound

Response:

{
  "items": [
    {
      "id": "uuid",
      "direction": "inbound",
      "provider_message_id": "incoming-1",
      "internet_message_id": "<msg-1@example.com>",
      "subject": "Your verification code",
      "from": "sender@example.com",
      "to": ["agent@example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "text": "Use 123456 to finish login.",
      "html": "<p>Use <strong>123456</strong> to finish login.</p>",
      "attachments": [],
      "headers": {},
      "parsed_data": {
        "verification_codes": ["123456"]
      },
      "status": "received",
      "received_at": "2026-03-13T00:00:00+00:00",
      "sent_at": null,
      "created_at": "2026-03-13T00:00:00+00:00"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xM1QwMDowMDowMCswMDowMCIsImlkIjoiZmYyOTk4ZDYtYjI3YS00ZWIwLThmMzYtMjY5ODJhNDk0YzQ2In0"
}

Behavior:

• results are ordered by created_at descending with id as a stable tie-breaker
• pass next_cursor to fetch the next page
• 400 is returned for an invalid cursor or missing inbox
• Email uses cursor pagination because inbox state is a newest-first event stream; SMS uses offset, while wallet intents follow the same cursor pattern as email

GET /v1/email/messages/{message_id}

Fetch one stored message from the authenticated inbox.

Errors:

• 400 no email inbox provisioned
• 401 invalid AGNT_KEY
• 404 message not found

POST /v1/email/send

Send email from the provisioned inbox.

Request:

{
  "to": ["user@example.com"],
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "subject": "Hello",
  "body_text": "Plain text",
  "headers": {
    "X-Campaign": "spring-launch"
  },
  "category": "transactional"
}

Response:

{
  "status": "sent",
  "data": {
    "id": "uuid",
    "direction": "outbound",
    "status": "queued"
  }
}

Behavior:

• sponsor-level send rate limits are enforced
• custom domains must already be verified
• beta only supports category: "transactional"
• marketing is not available in beta
• reply_to is not available in beta
• body_html is not available in beta
• invalid recipient emails, sensitive headers, more than 20 recipients, and body_text payloads over 256 KB return 422
• send throttling returns 429 with Retry-After: 5

POST /v1/email/reply/{message_id}

Reply in-thread to a stored inbound message.

Request:

{
  "body_text": "Thanks for your message"
}

Response shape matches POST /v1/email/send.

Errors:

• 400 no email inbox provisioned
• 400 source message is not a replyable inbound thread
• 401 invalid AGNT_KEY
• 404 source message not found