API Reference

Complete endpoint reference for the Ordian Mail API. Base URL: https://mail-api.ordian.ai

ℹ️ NoteAll paid endpoints require an X-PAYMENT header with a signed x402 payment. See Authentication for details.

Inboxes

Create inbox

POST/v1/inboxes

Create a new email inbox. Returns a unique email address.

Request body:

Parameter	Type	Description
`display_name`	string	Human-readable name for the inbox (max 200 chars)
`username`	string	Optional local part. On shared domain, a random suffix is appended. On custom domains, exact username is used. Pattern: ^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$
`metadata`	object	Arbitrary JSON metadata to attach to the inbox
`domain_id`	uuid	ID of a verified custom domain to create the inbox on

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "myagent-a4f2@mail.ordian.ai",
  "display_name": "My Agent",
  "owner_wallet": "0x857b...",
  "status": "active",
  "expires_at": "2026-04-01T12:00:00Z",
  "created_at": "2026-03-02T12:00:00Z",
  "metadata": null
}

List inboxes

GET/v1/inboxes?wallet={address}

List all inboxes belonging to a wallet address.

Parameter	Type	Description
`wallet`*	string	EVM wallet address (lowercased)

Renew inbox

POST/v1/inboxes/{id}/renew

Extend an inbox's TTL by 30 days.

Delete inbox

DELETE/v1/inboxes/{id}

Permanently delete an inbox, all messages, and webhooks.

Messages

Send email

POST/v1/send

Send an email from an inbox. Supports text, HTML, markdown, attachments, and threading.

Request body:

Parameter	Type	Description
`inbox_id`*	uuid	Inbox to send from
`to`*	string \| string[]	Recipient email address(es). Single string or array (max 50)
`subject`*	string	Email subject (max 998 chars)
`text`*	string	Plain text body (max 256KB)
`html`	string	Raw HTML body (max 512KB). Takes priority over markdown.
`markdown`	string	Markdown body — rendered to email-safe HTML with inline styles. Ignored if html is also provided. Ideal for AI agents.
`cc`	string[]	CC recipients (max 50)
`bcc`	string[]	BCC recipients (max 50)
`in_reply_to`	string	Message ID to thread against
`attachments`	object[]	File attachments (max 10). Each: { filename, content (base64), content_type? }

Response:

{
  "id": "msg-uuid",
  "message_id": "<uuid@mail.ordian.ai>",
  "thread_id": "msg-uuid",
  "status": "queued"
}

ℹ️ NoteMessages start as queued. Check delivery status via GET /v1/messages/:id/status.

List messages

GET/v1/inboxes/{id}/messages

List messages in an inbox with pagination.

Parameter	Type	Description
`thread_id`	uuid	Filter by thread ID
`limit`	integer	Max results (default 50, max 100)
`offset`	integer	Pagination offset (default 0)

Response:

{
  "data": [
    {
      "id": "msg-uuid",
      "inbox_id": "inbox-uuid",
      "thread_id": null,
      "direction": "inbound",
      "from_address": "sender@example.com",
      "to_address": "inbox@mail.ordian.ai",
      "subject": "Hello",
      "text_body": "Message content...",
      "html_body": null,
      "message_id": "<abc@sender.com>",
      "in_reply_to": null,
      "references_header": null,
      "status": null,
      "received_at": "2026-03-02T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Read a message

GET/v1/messages/{id}

Get a single message by ID.

Get delivery status

GET/v1/messages/{id}/status

Get delivery status and event history for an outbound message. Status: queued → delivered | bounced | deferred | failed.

Response:

{
  "id": "msg-uuid",
  "to": "recipient@example.com",
  "status": "delivered",
  "message_id": "<uuid@mail.ordian.ai>",
  "events": [
    {
      "event": "delivered",
      "diagnostic_code": "250 OK",
      "remote_server": "dns; gmail-smtp-in.l.google.com",
      "created_at": "2026-03-02T12:01:00Z"
    }
  ]
}

Webhooks

Register webhook

POST/v1/webhooks

Parameter	Type	Description
`inbox_id`*	uuid	Inbox to watch
`url`*	string	Webhook URL (max 2048 chars)
`events`	string[]	Event types: "message.received", "inbox.expiring", "inbox.expired". Default: ["message.received"]

Response:

{
  "id": "wh-uuid",
  "inbox_id": "inbox-uuid",
  "url": "https://my-agent.example.com/webhook",
  "events": "message.received",
  "secret": "whsec_...",
  "active": true,
  "created_at": "2026-03-02T12:00:00Z"
}

💡 TipUse the secret to verify webhook signatures. The server sends an X-Signature-256 header with each delivery.

List webhooks

GET/v1/webhooks?inbox_id={uuid}

List webhooks, optionally filtered by inbox.

List deliveries

GET/v1/webhooks/{id}/deliveries

View delivery log with retry history.

Retry delivery

POST/v1/webhooks/deliveries/{id}/retry

Retry a failed webhook delivery.

Custom Domains

Register domain

POST/v1/domains

Parameter	Type	Description
`domain`*	string	Domain name (auto-lowercased). Pattern: valid hostname, 3-253 chars.

Response includes DNS instructions:

{
  "id": "domain-uuid",
  "domain": "agent.example.com",
  "verified": false,
  "verify_token": "abc123def456",
  "dns_instructions": [
    { "type": "TXT", "name": "agent.example.com", "value": "x402-verify=abc123def456" },
    { "type": "MX", "name": "agent.example.com", "value": "mail.ordian.ai", "priority": 10 },
    { "type": "CNAME", "name": "dkim1._domainkey.agent.example.com", "value": "..." }
  ]
}

Verify domain

POST/v1/domains/{id}/verify

Check DNS records (TXT, MX, DKIM) and verify the domain.

List domains

GET/v1/domains?wallet={address}

List domains belonging to a wallet.

Suppression List

Addresses that hard-bounce are added to the suppression list. Emails to suppressed addresses are blocked (422 response).

List suppressed addresses

GET/v1/suppression

Paginated list of suppressed email addresses.

Check address

GET/v1/suppression/{address}

Check if a specific address is suppressed.

Remove from suppression

DELETE/v1/suppression/{address}

Remove an address from the suppression list. Use with caution.

Admin

Service metrics

GET/v1/admin/metrics

Aggregate metrics: inbox counts, message volumes, bounce rates, domain/webhook stats.

Health

Health check

GET/health

Service health check.

Response:

{
  "status": "ok",
  "service": "x402-agentmail",
  "version": "1.0.0",
  "uptime": 86400,
  "checks": {
    "database": "ok"
  }
}

Agent Skill file

GET/skill.md

Download the SKILL.md file for AI agent integration.