Quickstart

By the end of this page, your agent will have its own @agentmail.to email inbox to send and receive emails.

0. Get an API Key

Generate an API Key from the AgentMail Console:

Set it as an environment variable:

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

Or sign up from the CLI

Put your own email address in and you’ll get a 6-digit code to verify.

Until you verify, the inbox can only send to that one address, so an agent signing itself up should start by emailing its human to ask for the code.

npm install -g agentmail-cli

agentmail agent sign-up \
  --human-email "[email protected]" \
  --username "my-agent"

export AGENTMAIL_API_KEY="<api_key from the response>"
agentmail agent verify --otp-code "<6-digit code>"

Sign-up returns your credentials and an instructions field written for the agent doing the setup. The api_key is not shown again, so store it before anything else (values below abridged):

{
  "api_key": "am_us_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "inbox_id": "[email protected]",
  "email": "[email protected]",
  "organization_id": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",
  "instructions": "Store the api_key now; it is not shown again. Until you verify, this inbox can send only to [email protected]. Email your human there for the 6-digit code, then run: agentmail agent verify --otp-code <code> ..."
}

1. Install and authenticate

You can use AgentMail with the CLI, the API, or the TypeScript and Python SDKs. Install one and make a first call to check that your key works.

npm install -g agentmail-cli
agentmail inboxes list

2. Create an inbox

An inbox is an email address your agent owns. It can receive mail sent to that address and send mail from it. One inbox is all you need for this walkthrough.

You can set these fields when creating an inbox:

agentmail inboxes create --display-name "Support agent"

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

{
  "organization_id": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",
  "pod_id": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",
  "inbox_id": "[email protected]",
  "email": "[email protected]",
  "display_name": "Support agent",
  "created_at": "2026-08-23T09:26:01Z",
  "updated_at": "2026-08-23T09:26:01Z"
}

Save two fields from the response:

• inbox_id is what you pass to API calls. You will send from it in the next step and reply from it later.
• email is the inbox’s address. It is where you will send a test email in step 4.

3. Test sending emails

Send an email from your new inbox to the email account you use every day (Gmail, Outlook, or any client). Give it a subject and a line of text.

You should find this email in that account moments later, sent from your agent’s address.

agentmail inboxes:messages send \
  --inbox-id "<inbox_id>" \
  --to "[email protected]" \
  --subject "Hello from my agent" \
  --text "First email from my agent."

The send returns the new message’s message_id and the thread_id of the conversation it starts. You’ll use this to reply or follow-up in the same email thread.

{
  "message_id": "<010001a02e069a11-3c52b1de-91f7-4d02-b1cd-6a2e40c3f7aa-000000@email.amazonses.com>",
  "thread_id": "7d54a1cf-20b8-4e19-9d63-52c40a8e2b91"
}

In your agent’s inbox, the message you sent carries the sent label when you list messages.

4. Test receiving emails

Open your normal email account (Gmail, Outlook, or any client) and send an email to the address in your new inbox’s email field, for example [email protected]. Give it a subject and a line of text.

You should find this email up top when you list all messages in your inbox.

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

Delivery usually completes within about two seconds, so listing right after you send normally shows the message.

Messages come back newest first. The email you sent carries the received label, and its from is your own address:

{
  "count": 1,
  "messages": [
    {
      "inbox_id": "[email protected]",
      "thread_id": "3368f82c-77e7-4cb1-8071-bbf3597c8af2",
      "message_id": "<010001a02e0497eb-fa6483d8-4007-4a83-b2e9-f2f363e1e07e-000000@email.amazonses.com>",
      "labels": ["received", "unread"],
      "timestamp": "2026-08-23T09:47:28Z",
      "from": "You <[email protected]>",
      "to": ["[email protected]"],
      "subject": "Hello AgentMail",
      "preview": "Testing my new agent inbox.",
      "size": 4619,
      "created_at": "2026-08-23T09:47:28Z",
      "updated_at": "2026-08-23T09:47:28Z"
    }
  ]
}

The list returns a preview of each message. To read the full body, get the message by its message_id:

agentmail inboxes:messages get \
  --inbox-id "<inbox_id>" \
  --message-id "<message_id>"

{
  "inbox_id": "[email protected]",
  "thread_id": "3368f82c-77e7-4cb1-8071-bbf3597c8af2",
  "message_id": "<010001a02e0497eb-fa6483d8-4007-4a83-b2e9-f2f363e1e07e-000000@email.amazonses.com>",
  "labels": ["received", "unread"],
  "from": "You <[email protected]>",
  "to": ["[email protected]"],
  "subject": "Hello AgentMail",
  "text": "Testing my new agent inbox.",
  "timestamp": "2026-08-23T09:47:28Z"
}

5. Test replying to an email

You will need the received email’s message_id.

This is different from its thread_id:

• message_id identifies one individual message: the one that arrived, or the reply. Every message has its own.
• thread_id identifies the conversation that groups those messages together. The received message and your reply share the same thread_id.

Fetching the whole thread by its thread_id gives your agent the full conversation context in one call, instead of getting messages one by one. Messages come back oldest first, so the last element is the newest:

agentmail threads get \
  --thread-id "<thread_id>"

Now send the reply. It only needs the message_id of the message you are answering:

agentmail inboxes:messages reply \
  --inbox-id "<inbox_id>" \
  --message-id "<message_id>" \
  --text "Thanks, got your message."

The reply returns a new message_id and the same thread_id as the message it answered:

{
  "message_id": "<010001a02e05056f-80067f0e-aa54-4e6a-a490-18a590095f40-000000@email.amazonses.com>",
  "thread_id": "3368f82c-77e7-4cb1-8071-bbf3597c8af2"
}

Next Steps