Workflows

These workflows show how to chain AgentPost MCP tools together to accomplish end-to-end tasks. Each workflow maps directly to a set of sequential tool calls your agent makes.

Receive email
Send email
Read threads
Attachments

Use this workflow to create a temporary inbox, wait for a message to arrive, and clean up afterward. This is the most common AgentPost pattern — for example, automating sign-up verification flows.

Create a mailbox

Call CreateMailbox with no arguments to get a new address on the default AgentPost domain.

// Tool: CreateMailbox
// Input: {}
// Output:
{
  "id": "mbx_01abc",
  "email_address": "calm.brook-42@agent.agentpost.email",
  "domain": "agent.agentpost.email",
  "can_send": false,
  "created_at": "2026-03-31T10:00:00Z"
}

The email_address field is the address your agent hands off to whatever external system needs to send you an email.

Use the address externally

Submit the email address to the service you’re automating — a sign-up form, a password reset flow, a notification trigger, etc. The mailbox starts accepting mail immediately after creation.

Wait for the email to arrive

Call WaitForEmail with the address. The tool streams a notifications/progress event every 2 seconds so your agent knows it’s still running, then returns the full message when it arrives.

// Tool: WaitForEmail
// Input:
{
  "email_address": "calm.brook-42@agent.agentpost.email",
  "timeout": 60,
  "format": "html2text"
}
// Output (on success):
{
  "status": "received",
  "id": "msg_01xyz",
  "subject": "Verify your email address",
  "from": "noreply@example.com",
  "text_content": "Click here to verify: https://example.com/verify?token=abc123",
  "thread_id": "thr_01def",
  "has_attachments": false
}

WaitForEmail only detects emails that arrive after the tool is called. Always call CreateMailbox before submitting the address externally, and call WaitForEmail before you expect the message to arrive.

If the timeout expires before a message arrives, the response returns "status": "timeout". Your agent can call WaitForEmail again to extend the wait, or fall back to ListMailboxEmails to check for messages that arrived during the gap.

Or: list and read emails manually

Instead of WaitForEmail, your agent can poll by calling ListMailboxEmails to see all messages in the inbox, then ReadEmail to fetch the full content of a specific one.

// Tool: ListMailboxEmails
// Input:
{ "email_address": "calm.brook-42@agent.agentpost.email" }

// Tool: ReadEmail
// Input:
{ "message_id": "msg_01xyz", "format": "html2text" }

Use include_body: true on ListMailboxEmails if you want previews without an extra ReadEmail round trip.

Clean up

Delete the email or the entire mailbox when your workflow is done.

// Tool: DeleteEmail
// Input:
{ "message_id": "msg_01xyz" }

// Or remove everything at once:
// Tool: DeleteMailbox
// Input:
{ "email_address": "calm.brook-42@agent.agentpost.email" }

Both operations are irreversible. DeleteMailbox cascades to all messages in the inbox.

Use this workflow to register a custom domain, verify it, and send outbound email from a mailbox on that domain. Domain setup is a one-time step — once your domain is active, skip straight to creating a mailbox and calling SendEmail.

Add your domain

Call AddDomain with the domain name you want to use for sending.

// Tool: AddDomain
// Input:
{ "domain": "example.com" }
// Output:
{
  "id": "dom_01abc",
  "domain": "example.com",
  "status": "pending_dns",
  "verification_token": "ap-verify-abc123",
  "message": "Configure DNS records and call VerifyDomain to activate."
}

AgentPost queues a job to provision DNS records with the sending provider. Use ListDomains to poll the status and retrieve the exact records to configure once they’re ready.

Configure DNS at your registrar

Add the required DKIM, SPF, and DMARC records at your domain registrar. The exact record values come from ListDomains once the provider has set them up.

DNS propagation can take minutes to hours depending on your registrar and TTL settings. You don’t need to wait — call VerifyDomain and it will report which checks pass and which are still pending.

Verify the domain

Call VerifyDomain to trigger DNS checks. When all checks pass, the domain transitions to pending_warmup and begins a 72-hour warmup period.

// Tool: VerifyDomain
// Input:
{ "domain": "example.com" }
// Output:
{
  "domain": "example.com",
  "status": "pending_warmup",
  "verification_passed": true,
  "verified_at": "2026-03-31T12:00:00Z",
  "warmup_ends_at": "2026-04-03T12:00:00Z",
  "dns_checks": { "dkim": true, "spf": true, "dmarc": true }
}

You can call VerifyDomain multiple times to re-check. During warmup, your domain can send up to 10 emails per day. After warmup completes, the limit increases to 50 per day (configurable).

Create a mailbox on your domain

Call CreateMailbox with the domain parameter to create a sending-capable mailbox. The domain must be in pending_warmup or active status.

// Tool: CreateMailbox
// Input:
{ "domain": "example.com" }
// Output:
{
  "id": "mbx_02def",
  "email_address": "swift.river-7@example.com",
  "domain": "example.com",
  "can_send": true,
  "created_at": "2026-03-31T12:05:00Z"
}

Send the email

Call SendEmail with the mailbox address as the sender. The message is queued immediately and dispatched via the sending provider.

// Tool: SendEmail
// Input:
{
  "from_email_address": "swift.river-7@example.com",
  "to": ["recipient@example.org"],
  "subject": "Hello from AgentPost",
  "body": "This message was sent by an AI agent via the AgentPost MCP API.",
  "html_body": "<p>This message was sent by an AI agent via the AgentPost MCP API.</p>"
}
// Output:
{
  "message_id": "msg_02ghi",
  "status": "queued"
}

To send a reply that threads correctly in email clients, pass the in_reply_to field with the Message-ID of the email you’re replying to.

Use this workflow when your agent needs to read or participate in multi-message conversations, not just individual emails.

List threads in a mailbox

Call ListThreads to get a summary of all conversations, sorted by most recent activity. This returns compact summaries — no message bodies — to minimize token usage.

// Tool: ListThreads
// Input:
{
  "email_address": "calm.brook-42@agent.agentpost.email",
  "limit": 20
}
// Output:
{
  "mailbox": { "id": "mbx_01abc", "email_address": "calm.brook-42@agent.agentpost.email" },
  "thread_count": 3,
  "threads": [
    {
      "thread_id": "thr_01def",
      "subject": "Your verification code",
      "message_count": 1,
      "latest_date": "2026-03-31T12:10:00Z",
      "latest_preview": "Your verification code is 482910...",
      "participants": ["noreply@example.com"],
      "has_attachments": false
    }
  ],
  "next_cursor": null
}

Pass next_cursor from the response back as cursor to paginate through more threads.

Read a full thread

Call ReadThread with the thread_id to get all messages in the conversation, in chronological order.

// Tool: ReadThread
// Input:
{
  "thread_id": "thr_01def",
  "format": "html2text"
}
// Output:
{
  "thread_id": "thr_01def",
  "subject": "Your verification code",
  "message_count": 2,
  "messages": [
    {
      "id": "msg_01xyz",
      "from": "noreply@example.com",
      "date": "2026-03-31T12:10:00Z",
      "direction": "inbound",
      "text_content": "Your verification code is 482910.",
      "has_attachments": false
    },
    {
      "id": "msg_02abc",
      "from": "swift.river-7@example.com",
      "date": "2026-03-31T12:15:00Z",
      "direction": "outbound",
      "text_content": "Thank you, I have verified the account.",
      "has_attachments": false
    }
  ]
}

Each message includes a direction field — inbound for received messages, outbound for sent ones.Use the limit parameter to retrieve only the most recent N messages in a long thread, still in chronological order.

Or: discover threads while reading individual emails

When you call ReadEmail, the response includes thread_id and thread_message_count. If thread_message_count is greater than 1, there are more messages in the conversation — call ReadThread with the returned thread_id to get the full context.

// Tool: ReadEmail
// Output (partial):
{
  "id": "msg_01xyz",
  "subject": "Re: Your verification code",
  "thread_id": "thr_01def",
  "thread_message_count": 3
}

// thread_message_count > 1 → call ReadThread
// Tool: ReadThread
// Input:
{ "thread_id": "thr_01def" }

WaitForEmail also returns a thread_id in its response so your agent can immediately escalate to ReadThread if the arriving message is part of an ongoing conversation.

Use these patterns when your agent needs to download attachments from received emails or send outbound messages with file attachments.

Download attachments from a received email

Call ReadEmail to get the message content and attachment metadata, then call DownloadAttachment for each file you need.

// Tool: ReadEmail
// Input:
{ "message_id": "msg_01xyz", "format": "html2text" }
// Output (partial):
{
  "id": "msg_01xyz",
  "subject": "Your invoice",
  "has_attachments": true,
  "attachment_count": 1,
  "attachments": [
    {
      "id": "att_01abc",
      "filename": "invoice.pdf",
      "mime_type": "application/pdf",
      "size": 54321
    }
  ]
}

// Tool: DownloadAttachment
// Input:
{ "attachment_id": "att_01abc" }
// Output:
{
  "id": "att_01abc",
  "filename": "invoice.pdf",
  "mime_type": "application/pdf",
  "size": 54321,
  "content_base64": "JVBERi0xLjQK..."
}

Attachments larger than 10 MB cannot be downloaded via MCP. Download large files from the AgentPost web interface instead.

Send an email with attachments

Base64-encode each file and pass them in the attachments parameter of SendEmail.

// Tool: SendEmail
// Input:
{
  "from_email_address": "support@example.com",
  "to": ["client@example.org"],
  "subject": "Your report is ready",
  "body": "Please find your report attached.",
  "attachments": [
    {
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "content_base64": "JVBERi0xLjQK..."
    }
  ]
}
// Output:
{
  "message_id": "msg_02ghi",
  "status": "queued",
  "attachment_count": 1
}

You can include up to 20 attachments per message. The per-attachment and total size limit is 25 MB.

Get Started

Mailboxes

Sending Email

MCP API

Account