Documentation Index
Fetch the complete documentation index at: https://docs.agentpost.email/llms.txt
Use this file to discover all available pages before exploring further.
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"
}
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.
"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" }
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."
}
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 }
}
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"
}
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
}
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
}
]
}
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
}