2 posts tagged with "tutorial"

Most email MCP servers let your AI client send email. That is the easy half. The harder half is letting it receive replies, track delivery events, and maintain conversation context across a thread. This tutorial shows you how to wire both halves together using the mailbot MCP server.

If you have searched for "MCP email server" or "email MCP server" and landed on tutorials that only cover outbound, you already know the gap. MailerCheck's roundup of 6 email MCP servers confirms that the only two-way option in the list is a Gmail relay through Zapier. For developers who want a purpose-built inbox that their AI agent can own end to end, that is a meaningful gap.

This tutorial fills it. By the end, your MCP-compatible AI client will be able to create an inbox, send email from it, read replies, and check delivery events.

What You Will Build​

An AI agent workflow backed by a real mailbot inbox. Your AI client exposes 13 MCP tools that map directly to mailbot's API surface: inbox management, message sending, reply handling, thread reading, and delivery event inspection. You type a natural language instruction, and the client calls the right tool.

This is useful for agentic tasks like: send a follow-up to anyone who replied to yesterday's campaign, check whether my outbound message was delivered, or create a throwaway inbox for this test scenario and clean it up when done.

Prerequisites​

Before you start:

• Node.js 18 or later installed on your machine (the MCP server runs via npx)
• An MCP-compatible AI desktop client that supports external MCP servers via a JSON config file
• A mailbot account and API key from getmail.bot

No local build step required. The package ships prebuilt to npm.

Step 1: Understand How MCP Servers Work​

MCP (Model Context Protocol) lets an AI client call external tools in the same way a developer calls an API. According to the official MCP documentation, servers expose tools as typed functions. When you send a message to your AI client, it inspects the available tools, decides which one matches your intent, and executes it. The result comes back as context for the next response.

For email, this means your AI client becomes a first-class email actor rather than a text generator that happens to mention email addresses. It can actually create inboxes, send messages, and read what comes back.

Step 2: Install the mailbot MCP Server​

No manual install is required. The package runs on demand via npx, so your AI client fetches and executes it automatically on first launch.

The package is published at @yopiesuryadi/mailbot-mcp on npm. If you want to inspect the package before running it, you can pull it manually:

npx @yopiesuryadi/mailbot-mcp --help

This confirms the package resolves and prints the available tool list.

Step 3: Configure the MCP Server in Your AI Client​

Your MCP-compatible AI client reads a JSON config file to discover external servers. The exact file location varies by client. Common locations:

Add the following block to your client's MCP servers config:

{
  "mcpServers": {
    "mailbot": {
      "command": "npx",
      "args": ["-y", "@yopiesuryadi/mailbot-mcp"],
      "env": {
        "MAILBOT_API_KEY": "mb_test_xxx"
      }
    }
  }
}

Replace mb_test_xxx with your actual mailbot API key from your account dashboard.

Save the file and restart your AI client. If the client has a tools or connectors panel, you should see "mailbot" listed with its 13 available tools. That confirms the server is running and connected.

Note: the MCP server is at v1 and has not been tested across every AI client configuration. If your client does not surface the tools after restart, check that the config JSON is valid and that Node.js is accessible on your system PATH.

Step 4: Create an Inbox via MCP​

Once the server is connected, you can talk to your AI client in plain language. To create a new inbox, try a prompt like:

Create a new mailbot inbox named "support-test"

Your AI client will call the create_inbox tool, which maps to client.inboxes.create in the mailbot SDK. The tool returns the inbox details including its assigned email address.

You can list existing inboxes with:

List my mailbot inboxes

And retrieve details for a specific one with:

Get the inbox with ID inbox_abc123

Step 5: Send Email via MCP​

With an inbox created, sending is one instruction away:

Send an email from my support-test inbox to recipient@example.com with the subject "Hello from mailbot MCP" and a plain text body saying "This was sent by my AI agent."

The client calls the send_message tool under the hood. This is meaningfully different from send-only email MCP servers like Mailtrap's MCP integration, which only expose a single outbound send tool. With mailbot, the same session that sends can also receive and inspect.

You can also send HTML:

Send an HTML email from support-test to recipient@example.com. Subject: "Welcome". Body: a simple HTML welcome message with a bold heading.

Step 6: Receive and Read Email via MCP​

When a reply arrives at your mailbot inbox, your AI client can read it:

List the latest messages in my support-test inbox

This calls list_messages and returns subject, sender, snippet, and thread ID for each message. To read a full message:

Get the full content of message msg_xyz789

To search across messages:

Search my support-test inbox for messages from sender@example.com

The search_messages tool accepts sender, subject keywords, date ranges, and label filters, so your agent can do targeted retrieval without reading the entire inbox.

If you are building an automated flow and need to wait for a reply before proceeding, the wait_for_message tool (backed by client.messages.waitFor) polls until a matching message arrives or a timeout is reached. This is useful for test flows where you send a message and need to assert on the reply.

Step 7: Check Delivery Events via MCP​

Sending a message is the start, not the end. Your AI client can also inspect what happened to each message after delivery.

Check the delivery events for thread thread_abc123

This calls list_events for the thread, returning a timeline of events (queued, delivered, opened, bounced, and so on). You can also retrieve a single event:

Get event details for event evt_123

This is useful for agentic tasks like: "Send a follow-up only if the first message was delivered but not opened." Your agent can check the event timeline, make a conditional decision, and act without you writing any conditional logic manually.

Step 8: Organize with Labels and Threads via MCP​

The 13 mailbot MCP tools also cover thread reading and label management. To view a full conversation thread:

Show me the full thread for thread_abc123

To label a message for downstream filtering:

Add the label "needs-followup" to message msg_xyz789

Labels work as lightweight state markers that persist on the message, so other tools or agents in your workflow can filter by them later.

What Is Next​

This tutorial covered the core loop: create inbox, send, receive, inspect events. The mailbot MCP server exposes the same API surface as the SDK, so everything in the mailbot documentation applies to what your AI client can do.

A few directions to explore from here:

• Event notifications: Set up a webhook to push inbound messages to your own endpoint, so your agent reacts in real time rather than polling.
• Domain verification: Verify a custom sending domain so outbound messages use your own address.
• Compliance checks: Use the compliance tools to run readiness checks before sending to a new list.

The MCP integration is v1. Feedback from real usage is how it improves. If you run into edge cases with your specific AI client configuration, the documentation is the right place to start: getmail.bot/docs/getting-started.

Sources​

• Mailtrap MCP Tutorial: Sending Email from an AI Desktop Client
• MailerCheck: Guide to Email MCP Servers (Plus, 6 You Can Use Today)
• Model Context Protocol: Build an MCP Server

Hook​

Most developers discover the limits of their email API only after something breaks in production. An agent sends a follow-up reply that lands outside the original thread. An inbound message arrives at a webhook endpoint and disappears with no way to replay it. A compliance audit asks for an audit log that was never generated. By then, migrating to a different provider is painful.

Choosing an email API for an AI agent is a different problem from choosing one for transactional email. A welcome email does not need to receive replies. An AI agent does. The decision criteria are not the same, and most comparison guides available today were written with transactional use cases in mind.

The Problem​

The standard comparison framework for email APIs focuses on deliverability, latency, and price per message. Those things matter, but they answer the wrong question for agents. When an agent manages an ongoing support conversation, a sales sequence, or an approval workflow, the relevant questions are: can the agent receive the reply, does the reply arrive in the right thread context, and what happens if the event notification fails?

A billion-request benchmark by Knock found that SendGrid's median API response time is 22ms, Postmark's is 33ms, and Resend's is 79ms. Those numbers matter for transactional throughput. But an agent waiting on a human reply is not measuring latency in milliseconds. It is measuring reliability over minutes and hours.

The industry has also converged on a comparison model that treats inbound email as a secondary feature, something bolted on via webhook rather than designed as a core primitive. AgentMail's 2026 comparison of the top providers found that most handle inbound email through stateless webhook routing with no persistent storage or threading. For transactional email, that is fine. For an agent that needs to read a reply, correlate it with a prior message, and continue a conversation, it is a significant gap.

The Insight​

The right question to ask before picking an email API for an agent is not "how fast is the send?" It is "can this API handle the full conversation loop?" That loop has seven distinct requirements, and providers differ on almost every one of them.

The Evaluation Framework​

1. Two-Way vs. Send-Only​

The most fundamental distinction. Send-only providers (AWS SES at its core, older SendGrid configurations) give you an endpoint for outbound email and nothing more. Two-way providers give you both a send path and a receive path.

The difference in architecture is significant. AgentMail's comparison found that SendGrid's inbound parse is stateless (no persistent storage, no threading) and Mailgun routes inbound email via webhook with no persistent inbox. Resend added inbound webhook support in 2025. AWS SES requires additional AWS infrastructure (S3, Lambda, SNS) to do anything useful with a received message.

For agents, the question is whether you want to build and maintain that additional layer yourself or use an API that treats two-way communication as a first-class primitive.

An API designed for the full conversation loop looks like this:

import { MailbotClient } from '@yopiesuryadi/mailbot-sdk';
const client = new MailbotClient({ apiKey: 'mb_test_xxx' });

// An email API for agents should handle the full cycle: send, receive, reply in thread
const inbox = await client.inboxes.create({ name: 'support-agent' });
const inbound = await client.messages.waitFor({ inboxId: inbox.id, direction: 'inbound', timeoutMs: 30000 });
await client.messages.reply({ inboxId: inbox.id, messageId: inbound.id, bodyText: 'Thanks for reaching out.' });

The waitFor method blocks until a reply arrives, which is exactly the pattern an agent running a turn needs.

2. MTA Ownership vs. Rented Infrastructure​

Who controls the mail transfer agent matters for deliverability configuration and high-volume cost. AWS SES runs its own MTA and prices per message ($0.10 per 1,000 emails sent and $0.10 per 1,000 received, per AgentMail's pricing table). SendGrid and Postmark operate their own infrastructure. Resend routes through established MTAs.

Providers that own their MTA can offer dedicated IPs, custom warm-up, and more direct control over reputation. Providers that abstract the MTA away trade that control for easier onboarding. For agents sending at modest volume (under 50,000 messages per month), MTA ownership is less important than the API surface above it. In regulated industries, dedicated IP configuration and reputation isolation become meaningful.

3. Thread Handling​

Email threading is governed by three headers: Message-ID, In-Reply-To, and References. RFC 2822 specifies that a reply's References field should include the parent's References plus the parent's Message-ID. When this chain is managed correctly, every major email client preserves the thread. When it breaks, replies land as new conversations.

Managing this manually in application code is straightforward for the first reply. It becomes error-prone after three or four turns when the References header needs to carry the full ancestry. An API that handles threading automatically removes this class of bug entirely.

AgentMail handles threading via built-in API support with automatic header management. SendGrid and SES do not manage thread state; the application is responsible for passing the correct headers on every reply. Resend's threading behavior is not documented as an automatic feature.

4. Event Notification Reliability​

When an inbound message triggers an event, what happens if your endpoint is down? This is where providers diverge significantly.

Mailtrap's flexibility comparison found that retry windows vary considerably across providers:

Beyond retry duration, the question is whether you can replay a specific event after the window expires. For agents that need to recover from a missed notification without re-triggering the full workflow, event replay is a meaningful capability.

5. Custom Domains with Full DNS Setup​

An AI agent sending from agent@support.yourcompany.com requires a custom domain with SPF, DKIM, and ideally DMARC records configured. The question is how much of that setup the provider automates.

All major providers support custom domains. The differences are in the verification flow, the time required, and whether the provider guides you through the full DNS record set or leaves gaps. AgentMail notes that SendGrid's time to first email is 10 to 15 minutes, Mailgun's is similar, and AWS SES requires sandbox approval that takes 24 to 48 hours for new users.

For agents deployed in enterprise environments, the ability to verify multiple domains and issue separate credentials per domain matters for tenant isolation.

6. Compliance Readiness​

Enterprise buyers commonly ask for SOC 2 Type II, ISO 27001, or equivalent certifications. For agents handling customer communication, audit logs (who sent what, when, and to whom) are also relevant.

This criterion is often invisible until a procurement process or security review surfaces it. Checking compliance posture before you build is faster than retrofitting.

7. Pricing Model​

Three pricing models exist: per-message, per-inbox (flat rate), and hybrid.

Per-message pricing (AWS SES at $0.10/1,000) is economical at high outbound volume but can become expensive if agents are also receiving large volumes. Per-inbox pricing (AgentMail's model, starting at $20/month for 10 inboxes and 10,000 messages) is predictable for deployments with a fixed number of agent inboxes. Flat-rate models (Postmark, Resend's Pro tier) are predictable up to a message ceiling, then require a tier upgrade.

For agents, the relevant calculation is the ratio of inbound to outbound messages. A support agent that receives 1,000 messages and sends 1,000 replies is doing 2,000 message operations. A per-message model bills both directions if the provider supports inbound; a per-inbox model does not change with message volume within the tier.

Comparison Table​

The table below summarizes each provider across the seven criteria. "Native" means the feature is a first-class API primitive. "Webhook" means the feature requires your application to handle state and persistence.

A few notes on reading this table honestly. SendGrid's 22ms p50 latency is the best measured across any provider in the Knock benchmark, and its 72-hour retry window is the longest available for event notifications. AWS SES has the most consistent error rates of any provider measured, with most days below 0.01%. These are real advantages for high-volume transactional use cases.

The providers that score highest on the agent-specific criteria (two-way, auto threading, event replay) are the newer ones: AgentMail and mailbot. Both are earlier-stage than SendGrid or SES, which means a tradeoff: more agent-native features, less operational history.

Where mailbot Stands​

mailbot is designed around the agent use case. Inboxes are programmable resources. Threads are tracked automatically with correct In-Reply-To and References headers on every reply. Event notifications include replay via client.events.replay(eventId). Compliance tooling is available via client.compliance.readiness() and client.auditLog.list(). Pricing is per-inbox, not per-message.

The honest caveat: mailbot is younger than SendGrid or Postmark, which means less operational track record at the top end of volume. If you are migrating an existing high-volume transactional email pipeline, that history matters. If you are building a new agent workflow from scratch, the agent-native API surface is a meaningful starting point advantage.

Close​

Not every agent needs all seven criteria. A simple outbound notification agent only needs criteria 2 and 5. An agent managing multi-turn customer conversations needs all seven, and a gap in any one of them will surface as a bug in production.

The providers that dominated email in 2015 were built for a world where email was a one-way notification channel. Agent workflows are a different problem, and the evaluation should reflect that. The mailbot comparison page maps each criterion to a working implementation.

Sources​

1. AgentMail, "5 Best Email API For Developers Compared [2026]" (2026-01-27): https://www.agentmail.to/blog/5-best-email-api-for-developers-compared-2026
2. Jeff Everhart / Knock via Dev.to, "We analyzed a billion email API requests: here's what we learned" (2026-03-12): https://dev.to/knocklabs/we-analyzed-a-billion-email-api-requests-heres-what-we-learned-j39
3. Ivan Djuric / Mailtrap, "5 Best Email APIs: Flexibility Comparison [2026]" (2026-03-13): https://mailtrap.io/blog/email-api-flexibility/
4. Postmark, "Best Email API" (2026-01-12): https://postmarkapp.com/blog/best-email-api
5. Reddit r/webdev, "Email API benchmarks for SendGrid, Amazon SES...": https://www.reddit.com/r/webdev/comments/1rrxxs5/email_api_benchmarks_for_sendgrid_amazon_ses/
6. IETF RFC 2822, "Internet Message Format": https://datatracker.ietf.org/doc/html/rfc2822