# agentMBOX > Email for AI agents. Programmatic REST API, IMAP/SMTP access, custom domains. Base URL: https://agentmbox.com ## Authentication All API requests require a Bearer token: Authorization: Bearer ai_your_api_key API keys are created from the dashboard at /dashboard/api-keys. Keys can be **scoped to a specific mailbox** (no need to pass `?mailbox=`) or **unscoped** (access all mailboxes owned by the account). Key format: `ai_` followed by 64 hex characters. --- ## Endpoints ### List emails GET /api/v1/mail Query parameters: - `mailbox` (string) — email address, e.g. agent@agentmbox.com. Not required if key is scoped. - `limit` (number) — max emails to return. Default 50, max 100. - `offset` (number) — pagination offset. Default 0. Example: curl "https://agentmbox.com/api/v1/mail?mailbox=agent@agentmbox.com&limit=10" \ -H "Authorization: Bearer ai_your_api_key" Response: { "mailbox": "agent@agentmbox.com", "emails": [ { "id": "M1234", "from": [{ "name": "Alice", "email": "alice@example.com" }], "to": [{ "email": "agent@agentmbox.com" }], "subject": "Hello from Alice", "receivedAt": "2026-03-10T12:00:00Z", "preview": "Hey, just wanted to check in about...", "isRead": false } ], "limit": 10, "offset": 0 } --- ### Get email GET /api/v1/mail/:id Query parameters: - `mailbox` (string) — not required if key is scoped. Path parameters: - `id` (string, required) — the email ID from the list endpoint. Example: curl "https://agentmbox.com/api/v1/mail/M1234?mailbox=agent@agentmbox.com" \ -H "Authorization: Bearer ai_your_api_key" Response: { "email": { "id": "M1234", "from": [{ "name": "Alice", "email": "alice@example.com" }], "to": [{ "email": "agent@agentmbox.com" }], "cc": null, "subject": "Hello from Alice", "receivedAt": "2026-03-10T12:00:00Z", "textBody": "Hey, just wanted to check in about the project.", "htmlBody": "

Hey, just wanted to check in about the project.

", "hasAttachment": false, "isRead": true } } --- ### Send email POST /api/v1/mail/send Request body (JSON): - `from` (string, required) — sender address. Must be a mailbox you own. - `to` (string or string[], required) — recipient(s). - `subject` (string, required) — subject line. - `text` (string) — plain text body. - `html` (string) — HTML body. If both text and html are provided, html takes precedence. Example: curl -X POST "https://agentmbox.com/api/v1/mail/send" \ -H "Authorization: Bearer ai_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "from": "agent@agentmbox.com", "to": "client@example.com", "subject": "Your report is ready", "text": "Hi, your weekly report has been generated." }' Response: { "success": true } Multiple recipients: { "from": "agent@agentmbox.com", "to": ["alice@example.com", "bob@example.com"], "subject": "Team update", "html": "

Weekly Update

Here are the highlights...

" } --- ### Delete email DELETE /api/v1/mail/:id Query parameters: - `mailbox` (string) — not required if key is scoped. Path parameters: - `id` (string, required) — the email ID to delete. Example: curl -X DELETE "https://agentmbox.com/api/v1/mail/M1234?mailbox=agent@agentmbox.com" \ -H "Authorization: Bearer ai_your_api_key" Response: { "success": true } --- ## Errors All errors return JSON with an `error` field: { "error": "You are not authorized to send from this address" } | Status | Meaning | |--------|---------| | 400 | Missing or invalid parameters | | 401 | Missing or invalid API key | | 403 | Not authorized for this resource | | 404 | Mailbox or email not found | | 502 | Mail server error (retry with backoff) | --- ## Management API These endpoints use **session cookie authentication** (same as the dashboard). They are available for programmatic account management. ### List domains GET /api/v1/domains Response: { "domains": [ { "id": "uuid", "domain": "example.com", "verified": false, "mxVerified": false, "spfVerified": false, "dkimVerified": false, "verificationToken": "agentmbox-verify-...", "dnsRecords": { "verification": { "type": "TXT", "name": "_agentmbox.example.com", "value": "agentmbox-verify-..." }, "mx": { "type": "MX", "name": "example.com", "value": "mail.agentmbox.com", "priority": 10 }, "spf": { "type": "TXT", "name": "example.com", "value": "v=spf1 include:mail.agentmbox.com ~all" } } } ] } ### Add custom domain POST /api/v1/domains Request body: - `domain` (string, required) — the domain name, e.g. "example.com" Response: returns the new domain object with `dnsRecords` showing which DNS records to create. ### Verify domain DNS POST /api/v1/domains/:id/verify Performs live DNS lookups to check TXT verification, MX, and SPF records. Updates the domain's verification status in the database. Response: { "verified": true, "txtVerified": true, "mxVerified": true, "spfVerified": true, "dkimVerified": false } ### Delete domain DELETE /api/v1/domains/:id Fails with 400 if the domain has mailboxes. Delete mailboxes first. ### List mailboxes GET /api/v1/mailboxes Response: { "mailboxes": [ { "id": "uuid", "address": "agent@agentmbox.com", "localPart": "agent", "domainName": "agentmbox.com", "displayName": "My Agent", "createdAt": "2026-03-10T12:00:00Z" } ] } ### Create mailbox POST /api/v1/mailboxes Request body: - `localPart` (string, required) — the part before @, e.g. "my-agent" - `domainId` (string, optional) — UUID of a verified custom domain. Omit for @agentmbox.com. - `displayName` (string, optional) — display name for the mailbox. ### Delete mailbox DELETE /api/v1/mailboxes/:id Permanently deletes the mailbox, all its emails, and associated API keys. --- ## IMAP Access Every mailbox supports standard IMAP. | Setting | Value | |----------|-------| | Server | mail.agentmbox.com | | Port | 993 | | Security | TLS (implicit) | | Username | your-agent@agentmbox.com | | Password | Mailbox password (shown once at creation) | --- ## SMTP Access Send via any SMTP client. | Setting | Value | |----------|-------| | Server | mail.agentmbox.com | | Port | 465 | | Security | TLS (implicit) | | Username | your-agent@agentmbox.com | | Password | Mailbox password | --- ## Pricing - **Free**: 1 mailbox on @agentmbox.com, REST API + IMAP, 100 emails/day. - **Pro ($5/domain/month)**: Unlimited mailboxes, custom domains, 1,000 emails/day per domain, DKIM signing.