> ## 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. # Workflows > Step-by-step guides for the most common AgentPost MCP use cases: receiving email, sending email, and reading threaded conversations. 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. 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. Call `CreateMailbox` with no arguments to get a new address on the default AgentPost domain. ```json theme={null} // 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. 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. 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. ```json theme={null} // 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. 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. ```json theme={null} // 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. Delete the email or the entire mailbox when your workflow is done. ```json theme={null} // 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`. Call `AddDomain` with the domain name you want to use for sending. ```json theme={null} // 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. 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. Call `VerifyDomain` to trigger DNS checks. When all checks pass, the domain transitions to `pending_warmup` and begins a 72-hour warmup period. ```json theme={null} // 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). Call `CreateMailbox` with the `domain` parameter to create a sending-capable mailbox. The domain must be in `pending_warmup` or `active` status. ```json theme={null} // 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" } ``` Call `SendEmail` with the mailbox address as the sender. The message is queued immediately and dispatched via the sending provider. ```json theme={null} // 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": "

This message was sent by an AI agent via the AgentPost MCP API.

" } // 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. 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. ```json theme={null} // 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. Call `ReadThread` with the `thread_id` to get all messages in the conversation, in chronological order. ```json theme={null} // 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. 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. ```json theme={null} // 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. Call `ReadEmail` to get the message content and attachment metadata, then call `DownloadAttachment` for each file you need. ```json theme={null} // 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. Base64-encode each file and pass them in the `attachments` parameter of `SendEmail`. ```json theme={null} // 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**.