Email infrastructure for AI agents is not one thing. It is a stack of six distinct layers, each handling a different aspect of how agents interact with email. Most teams discover this incrementally — they solve inbox creation, then hit the parsing problem, then the wait semantics problem, then outbound, then webhooks, then domains. Here is the complete picture upfront.

Layer 1: Inbox Management

The foundation. Every agent email workflow starts with creating an inbox and ends with deleting it. The API surface is small: create, list, and delete. The key requirement is speed — inbox creation must be fast enough to happen inline in an agent workflow without introducing meaningful latency. Milliseconds, not seconds.

  • POST /inboxes — create with optional username and custom domain
  • GET /inboxes — list inboxes for your organization
  • DELETE /inboxes/:id — delete inbox and all associated messages

Layer 2: Inbound Processing

When an email arrives, it is a raw MIME message. Agents do not want to deal with MIME parsing. The inbound processing layer handles all of this automatically before the email ever reaches your agent code.

  • MIME parsing: extract text and HTML bodies from multipart messages
  • OTP detection: regex and heuristic extraction of 4-8 digit verification codes
  • Magic link extraction: identify and extract verification, login, and activation links
  • Email threading: group messages into conversations by Message-ID and References headers
  • Attachment handling: store attachments separately, accessible via download URL

Layer 3: Wait Semantics

Waiting for an email is the core primitive in most agent workflows. The naive approach is a polling loop. The correct approach is long-polling: a single HTTP request that blocks until the email arrives and resolves instantly when it does.

// Layer 3: wait semantics in action
const { otp } = await client.messages.waitForOTP({
  inboxId: inbox.id,
  timeout: 30_000,  // max wait time in ms
});
// Resolves in <100ms if email is already there,
// or the moment it arrives if not.

Layer 4: Outbound Sending

Agents that only receive email are limited. Many workflows require the agent to reply, forward, or initiate email conversations. The outbound layer provides a simple send interface with proper SMTP authentication and thread management.

  • POST /inboxes/:id/send — send a new email from the inbox address
  • POST /inboxes/:id/reply — reply to a specific message, maintaining thread headers
  • POST /inboxes/:id/forward — forward a received message to another address
  • Outbound email is sent via authenticated SMTP relay with proper SPF/DKIM signing

Layer 5: Webhooks

Long-polling works for synchronous agent workflows where the agent is actively waiting. For asynchronous, queue-based architectures — where an agent task is suspended while waiting and resumed when email arrives — webhooks are the correct primitive. Configure a webhook URL and receive a POST request the moment an email is delivered to any inbox in your organization.

Layer 6: Domain and Identity

The final layer provides professional email identity for production deployments. Instead of @agentmailr.com, your agents can send and receive as @yourcompany.com. This requires domain verification and DNS configuration (MX, SPF, DKIM, DMARC), all handled through the dashboard with guided setup.

The Full Stack at a Glance

  • Layer 1 — Inbox Management: create, list, delete. Per-task lifecycle.
  • Layer 2 — Inbound Processing: MIME parsing, OTP detection, magic link extraction, threading.
  • Layer 3 — Wait Semantics: long-poll /wait and /otp. Zero polling loops.
  • Layer 4 — Outbound Sending: send, reply, forward. Authenticated SMTP relay.
  • Layer 5 — Webhooks: async event delivery for queue-based architectures.
  • Layer 6 — Domain and Identity: custom domains, DKIM, professional agent identity.

AgentMailr provides all six layers as a single hosted service. You do not need to assemble this stack yourself or manage any email server infrastructure.

Start Free

Get the complete agent email stack without building or operating any infrastructure. Free to start, no credit card required.