Quickstart

Create an inbox, send a test message to it, read the message, and reply on its thread.

All API requests use https://api.agentmail.to/v0 and Authorization: Bearer <API_KEY>.

Before you begin

You need an account and API key. Get one from the Introduction, then set these variables.

export AGENTMAIL_API_KEY="<API_KEY>"
export AGENTMAIL_BASE_URL="https://api.agentmail.to/v0"

Install and authenticate

Use the CLI for this walkthrough. curl, TypeScript, and Python use the same API.

npm install -g agentmail-cli
agentmail auth me

A successful organization-scoped key returns this shape. scope_id is the id of the key’s scope.

{
  "scope_type": "organization",
  "scope_id": "<organization_id>",
  "organization_id": "<organization_id>",
  "api_key_id": "<api_key_id>"
}

401 means the key is missing or invalid. 404 usually means the base URL is missing /v0.

Create an inbox

An inbox has an address-like inbox_id. The request body is optional; display_name helps identify this inbox later.

agentmail inboxes create \
  --display-name "Quickstart inbox"

Without a username, AgentMail generates one on the agentmail.to domain:

{
  "pod_id": "<pod_id>",
  "inbox_id": "<generated-username>@agentmail.to",
  "email": "<generated-username>@agentmail.to",
  "display_name": "Quickstart inbox",
  "created_at": "2026-07-13T09:15:04Z",
  "updated_at": "2026-07-13T09:15:04Z"
}

Save inbox_id. It is the inbox email address and is used in the remaining requests.

Send a test message

Send a message to the inbox you created. Use text, not body. The endpoint is POST /v0/inboxes/{inbox_id}/messages/send.

agentmail inboxes:messages send \
  --inbox-id "<inbox_id>" \
  --to "<inbox_id>" \
  --subject "Hello from the quickstart" \
  --text "This is a test message."

{
  "message_id": "<message_id>",
  "thread_id": "<thread_id>"
}

Find the received message

List the inbox messages. Delivery can take a moment.

agentmail inboxes:messages list \
  --inbox-id "<inbox_id>"

Messages are returned newest first. Unset optional fields are absent; next_page_token appears only when another page exists.

{
  "count": 1,
  "messages": [
    {
      "inbox_id": "<inbox_id>",
      "thread_id": "<thread_id>",
      "message_id": "<message_id>",
      "labels": ["received"],
      "timestamp": "2026-07-13T09:16:11Z",
      "from": "<inbox_id>",
      "to": ["<inbox_id>"],
      "subject": "Hello from the quickstart",
      "preview": "This is a test message.",
      "size": 1024,
      "created_at": "2026-07-13T09:16:11Z",
      "updated_at": "2026-07-13T09:16:11Z"
    }
  ]
}

Use the returned message_id for the reply. thread_id identifies the conversation containing both messages.

Reply on the thread

A reply targets message_id, not thread_id: POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply.

agentmail inboxes:messages reply \
  --inbox-id "<inbox_id>" \
  --message-id "<message_id>" \
  --text "Got it, replying from the quickstart."

The reply returns a new message_id and the original thread_id, using the same response shape as send. List the inbox again. Two messages with one thread_id confirm the loop worked.

Common mistakes

Missing /v0 in the base URL. Requests return 404 Not Found. Set AGENTMAIL_BASE_URL to exactly https://api.agentmail.to/v0.

Using body instead of text. The send and reply APIs accept text and/or html. Replace body with text.