Introduction
agentmail provides a complete email platform accessible via a REST API. Below are the core concepts you need to understand.
Inboxes
An inbox represents a real email mailbox. Each inbox maps to a Stalwart mailbox with its own email address (e.g. agent@yourdomain.com). Inboxes can send and receive email via the API or directly through IMAP/SMTP.
Key properties: inbox_id, email_address, username, domain, display_name, client_id
Messages
Messages are individual emails. You can send new messages, reply to received messages, reply-all to include all original recipients, and forward messages to other addresses. Each message includes the full email content (text, HTML, headers, attachments).
Operations: send, reply, reply-all, forward, list, get, update labels
Threads
Threads automatically group related messages using the Message-ID, In-Reply-To, and References headers. This gives you Gmail-like conversation threading out of the box.
Key properties: thread_id, subject, message_count, senders, recipients, preview
Domains
Custom domains let your agents send from branded addresses. When you add a domain, agentmail generates the required DNS records for SPF, DKIM, and DMARC. Once you add those records to your DNS provider and run verification, the domain is ready to use.
Status flow: PENDING → VERIFIED
Webhooks
Webhooks push real-time notifications to your application when email events occur. You configure a URL and select which event types to subscribe to. Each webhook delivery includes an HMAC signature for verification.
Event types: message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified
API Keys
All API requests require authentication via a Bearer token. API keys are created through the API or console and are prefixed with inai_. The full key is only shown once at creation time — store it securely.
Header: Authorization: Bearer inai_xxxx...
Native IMAP/SMTP
Every inbox created through the API also has full IMAP and SMTP access. This means you can connect any standard email client (Thunderbird, Apple Mail, etc.) to the same mailbox. The REST API and native protocols operate on the same underlying Stalwart mailbox, so changes are reflected everywhere.
Protocols: IMAP (port 993, TLS), SMTP (port 587, STARTTLS). Credentials are generated per-inbox at creation time.