# MailAPI — Full Reference for AI Systems

> MailAPI (https://mailapi.tech) is an API-first email infrastructure SaaS. Customers connect custom domains, provision mailboxes at scale, send via SMTP/IMAP-compatible relays, and automate inbound processing with REST APIs and signed webhooks. Background provisioning uses async tasks: create endpoints return `task_id`; clients poll matching `GET /get/...` endpoints until `status` is `completed` or `failed`.

Concise curated index: [llms.txt](https://mailapi.tech/llms.txt)

---
## Product Summary

**Core capabilities**
- Root domain and subdomain provisioning with DNS record guidance (MX, TXT verification, mail-host A)
- Single and bulk mailbox creation (API and dashboard)
- Inbox ingestion via `POST /api/v1/mail/inbound` or IMAP polling (Mailbridge) for active mailboxes
- Email retrieval, sync, read/delete, and attachment signed URLs
- Outbound webhook registration for `email.received`, `email.read`, `email.deleted`
- SMTP relay profiles and outbound compose (authenticated dashboard features)

**Typical workflow**
1. Add domain (API or dashboard) and publish DNS records
2. Verify DNS, then create mailboxes (single or bulk)
3. Send through your SMTP provider; receive via inbound API, IMAP poll, or webhooks
4. List/sync emails programmatically for automation pipelines

**Infrastructure**
- US-hosted email infrastructure
- Mail server integration via Mailcow; default IMAP host `imap.mailapi.tech`
- Inbound MX target example: `mail.mailapi.tech`

**Pricing (public homepage; live values are database-driven)**
- Plans include Starter, Pro, and Advanced tiers with monthly/annual billing
- Pro tier typically includes API access and priority support (see homepage pricing table for current limits and trial eligibility)
- Pricing page: https://mailapi.tech/pricing
- Machine-readable pricing: https://mailapi.tech/pricing.json

---
## Authentication & Conventions

- **API key format**: 32 characters (alpha-numeric)
- **Transport**: `Authorization: Bearer <key>` or `X-Api-Key: <key>`
- **Permissions**:
  - `read` — list/get tasks, list domains/mailboxes, email retrieval
  - `write` — create/delete domains and mailboxes, mark emails read, delete emails
  - `inbound` — `POST /api/v1/mail/inbound`
  - `webhook` — webhook CRUD
- **Plan gate**: Creating domains, subdomains, and mailboxes via API requires an active paid plan (admin accounts exempt)
- **Success shape**: `{ "status": "success", ... }`
- **Error shape**: `{ "status": "error", "reason": "..." }`
- **Task polling**: Async jobs return `task_id`; poll the documented `GET` task endpoint for that operation until `status` is `completed` or `failed`
- Background jobs return a `task_id`.
- Poll the matching get-task endpoint until `completed` or `failed`.
- Bulk domain deletes: up to 10 hostnames per request.
- Bulk mailbox deletes: up to 100 addresses per request.
- One bulk-delete request per 5 minutes per API key and IP.
- HTTP 422 validation errors do not count toward the cooldown.
- Active pricing plan required (admins exempt).

---
## Rate Limits & Cooldowns

| Surface | Limit |
|---------|-------|
| MCP (`/mcp/mailapi`) | 120 requests/min per API key |
| API read (`api-v1-read`) | 120 requests/min per API key |
| API create (`api-v1-create`) | 30 requests/min per API key |
| API inbound (`api-v1-inbound`) | 120 requests/min per API key |
| API webhooks CRUD (`api-v1-webhooks`) | 60 requests/min per API key |
| Bulk delete domains | 1 request per 5 minutes per API key |
| Bulk delete mailboxes | 1 request per 5 minutes per API key |
| Subdomain create | 1 successful batch per 5 min per domain and API key |
| Bulk mailbox create | 1 successful batch per 5 min per domain and API key |

HTTP `429` responses include rate-limit headers when throttled. Bulk-delete cooldowns also return `429` with a retry message.

---
## AI Agent Integration (MCP + REST)

**Discovery**
- Agent manifest: https://mailapi.tech/.well-known/agents.json
- Public skill: https://mailapi.tech/skill.md
- Agent playbooks: https://mailapi.tech/docs/agent-playbooks

**MCP server (HTTP)**
- Endpoint: https://mailapi.tech/mcp/mailapi
- Transport: JSON-RPC over HTTP POST
- Auth: `Authorization: Bearer <api_key>`, `X-Api-Key: <api_key>`, or `api_key` in tool arguments

**MCP tools**
| Tool | Purpose |
|------|---------|
| `list_domains` | List all domains for the authenticated tenant |
| `list_mailboxes` | List mailboxes for a domain (optional `include_credentials`) |
| `get_task_status` | Poll async task status by `task_id` |
| `list_emails` | List tenant emails with filters and cursor pagination |
| `create_domain` | Enqueue root domain creation (returns `task_id`) |
| `create_mailbox` | Enqueue single mailbox creation (returns `task_id`) |
| `create_subdomain` | Enqueue subdomain batch creation (returns `task_id`) |
| `create_bulk_mailboxes` | Enqueue bulk mailbox creation (returns `task_id`) |
| `delete_domain` | Enqueue bulk domain deletion (returns `task_id`) |
| `delete_mailbox` | Enqueue bulk mailbox deletion (returns `task_id`) |
| `register_webhook` | Register webhook endpoint (requires `webhook` permission) |

**MCP resources:** `openapi`, `getting-started`, `dns-verification`, `inbox-api`, `webhooks`
**MCP prompts:** `provision-mailbox-workflow`

**Hybrid workflow (recommended)**
1. Use MCP to inspect domains, mailboxes, emails, create/delete resources, register webhooks, and poll task status
2. Use REST (OpenAPI: https://mailapi.tech/openapi.json) for inbound POST, email show/delete, and webhook update/delete
3. Poll task completion via MCP `get_task_status` or REST `GET /api/v1/get/*`

**Cursor MCP config example**
```json
{
  "mcpServers": {
    "mailapi": {
      "url": "https://mailapi.tech/mcp/mailapi",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

---
## REST API — Domains

Base: `https://mailapi.tech/api/v1`

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| POST | `/create/domain` | write | Creates a new base domain in your MailAPI workspace and queues provisioning in the background. Invalid hostnames return HTTP 422 before enqueue; duplicates return HTTP 409. |
| GET | `/get/domain?task_id={id}` | read | Polls a root domain create task created by `POST /api/v1/create/domain`. `status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` returns HTTP 422 with `reason` from the task. |
| POST | `/create/sub-domain` | write | Creates up to 10 sub-domains under an existing parent domain in a single queued task. After a successful run: at most one request per 5 minutes per API key and parent domain. |
| GET | `/get/sub-domain?task_id={id}` | read | Polls a sub-domain batch task from `POST /api/v1/create/sub-domain`. `status` values are the same as other task endpoints (`queued`, `running`, `completed`, `failed`). |
| GET | `/list/domain` | read | Returns all domains for the API key owner account, keyed by domain name. `domain_type` is `root` or `sub`. |
| POST | `/delete/domain/bulk` | write | Queues removal of up to 10 domains (root or sub-domain hostnames) owned by your account. Deletes run sequentially on the mail server; there is no artificial delay between items. Cooldown: one successfully enqueued call per 5 minutes per API key and IP; HTTP 422 does not count. Mailbox bulk delete uses a separate counter of the same length. |
| GET | `/get/delete/domain/bulk?task_id={id}` | read | Polls a bulk domain delete task created by `POST /api/v1/delete/domain/bulk`. `status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` (task-level) returns HTTP 422 with `reason` from the task. |

**Platform limits (domains)**
- Up to 100 subdomains per parent domain (lifetime)
- Up to 10 subdomain labels per API batch; cooldown between batches (same parent + API key)
- Bulk domain delete: max 10 hostnames per request; 5-minute cooldown per key/IP

---

## REST API — Mailboxes

Base: `https://mailapi.tech/api/v1`

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| POST | `/create/mailbox/single` | write | Queues one mailbox creation request for a domain that belongs to your account. Invalid bodies return HTTP 422 before enqueue. Only numeric `0` for `Params.password` triggers auto-generation (string `"0"` is rejected). |
| POST | `/create/mailbox/bulk` | write | Queues a bulk mailbox provisioning task and returns a task ID for later retrieval. After a successful run: at most one bulk create per 5 minutes per API key and target hostname. |
| GET | `/get/mailbox/single?task_id={id}` | read | Fetches status and final result for a single mailbox provisioning task. `status` is `queued`, `running`, `completed`, or `failed`. While pending, `results` is often empty. |
| GET | `/get/mailbox/bulk?task_id={id}` | read | Fetches status and per-mailbox results for a bulk mailbox provisioning task. `status` follows the same lifecycle as single mailbox tasks. |
| POST | `/delete/mailbox/bulk` | write | Queues removal of up to 100 mailbox addresses owned by your account. Deletes run sequentially; there is no artificial delay between items. Cooldown: one successfully enqueued call per 5 minutes per API key and IP; HTTP 422 does not count. Domain bulk delete uses a separate counter of the same length. |
| GET | `/get/delete/mailbox/bulk?task_id={id}` | read | Polls a bulk mailbox delete task created by `POST /api/v1/delete/mailbox/bulk`. `total_email` mirrors the request size (count of addresses submitted), not the number successfully deleted. |
| GET | `/list/mailbox?domain={id}` | read | Returns all mailboxes for a specific owned domain, keyed by full email address. `imap_credentials` only when `include_credentials=true`. |

**Platform limits (mailboxes)**
- Up to 100 mailboxes per hostname (root or subdomain), independently per host
- Bulk UI batch: up to 25 mailboxes; API bulk: up to 100 per request
- Cooldown between bulk mailbox API requests per domain + API key (5 minutes)

---

## REST API — Inbox & Inbound

Base: `https://mailapi.tech/api/v1`

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| POST | `/mail/inbound` | inbound | Accepts inbound payloads for a tenant mailbox and queues processing. Optional fields include `from_name`, `cc`, `bcc`, `body_html`, `attachments`, and `headers`. Inbound processing is asynchronous. |
| GET | `/emails` | read | Returns tenant-scoped inbox emails with cursor pagination. Query is always tenant-isolated. |
| GET | `/emails/{email}` | read | Returns one tenant-scoped email with attachment metadata. Soft-deleted records are not returned from this endpoint. |
| GET | `/emails/sync?since={id}` | read | Incremental polling endpoint for new, updated, and deleted emails. Deleted emails are returned with deletion markers to support tombstones. |
| POST | `/emails/{email}/read` | write | Marks an email as read and emits an email.read webhook event. This endpoint is idempotent. |
| DELETE | `/emails/{email}` | write | Soft-deletes an email and emits an email.deleted webhook event. Record is soft deleted, not permanently removed. |
| GET | `/emails/{email}/attachments/{attachment}` | read | Returns a temporary signed attachment download URL. URL expires shortly after issuance. |

**Inbound required fields**: `message_id`, `from_email`, `to_email`, `subject`, `received_at` (ISO-8601)

**Optional inbound fields**: `from_name`, `cc[]`, `bcc[]`, `body_text`, `body_html`, `headers`, `in_reply_to`, `references[]`, `attachments[]`

**Accepted response**: `{ "status": "accepted", "message_id": "..." }`

**IMAP polling (Mailbridge)**: Laravel scheduler can run `mailbridge:poll-inbound` for active, provisioned mailboxes with IMAP credentials. Tenant HTTP inbound (`POST /mail/inbound`) is separate from IMAP polling.

---

## REST API — Webhooks

Base: `https://mailapi.tech/api/v1`

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| POST | `/webhooks` | webhook | Creates a tenant-scoped webhook target for email events. Deliveries are queued and signed using the webhook secret and timestamp headers. |
| GET | `/webhooks` | webhook | Returns tenant-scoped webhook endpoints. Each row includes `last_triggered_at` when the webhook has fired. |
| PATCH | `/webhooks/{webhook}` | webhook | Updates URL, events, or active state. Include at least one of `url`, `events`, or `is_active`. |
| DELETE | `/webhooks/{webhook}` | webhook | Deletes a tenant webhook endpoint. Permanent delete; queued delivery rows for this webhook are removed. |

**Events**: `email.received`, `email.read`, `email.deleted`

**Delivery headers**
- `X-Webhook-Signature`: HMAC-SHA256 of `{timestamp}.{raw_json_body}` using webhook secret
- `X-Webhook-Timestamp`: Unix timestamp

**Payload shape**
```json
{
  "event": "email.received",
  "timestamp": 1777290021,
  "data": { "email_id": 101, "mailbox_id": 10 }
}
```

---

Interactive docs: https://mailapi.tech/api/docs

---

OpenAPI JSON: https://mailapi.tech/openapi.json

---

## FAQ (plain text)

**How do I programmatically create email accounts?**
You can add domain or mailbox using our API or web interface. For automation, simply call the mailbox API endpoints with the required parameters. Check our API documentation https://mailapi.tech/api/docs for more details

**Can I use my own domain?**
Yes. You can add and use as many domains as you want by publishing the mail routing records (MX and mail-host A) to your DNS host. After that, you can create mailboxes and send/receive emails.

**Can I use sub-domains?**
Yes. From a verified domain, you can add sub domains. We allow up to 100 subdomains per parent

**Can I create emails on sub-domains?**
Yes, absolutely. You can create emails on sub-domains the same way as for the root domain, then use your SMTP IMAP API-compatible mail stack to send and receive emails.

**How many email addresses can I create?**
Each hostname (your apex domain and each sub-domain) supports up to 100 mailboxes on that host, independently of other hosts under the same apex. Please use mailboxes responsibly. Avoid unsolicited bulk emails or spam, as it can kill your mailbox and domain reputation overtime. We've built a best practices guidelines to help you get started. Check it out here: https://mailapi.tech/article/how-to-improve-email-deliverability-complete-guide-for-cold-high-volume-sending

**Do I need to configure DNS (SPF, DKIM, DMARC)?**
We provide you with MX and A records. Add them to your DNS host and verify them using the 'Verify DNS' button on our app. Obtain SPF, DKIM, and DMARC records from your SMTP provider and add them to your DNS host as well.

**Are there hidden limits or prices?**
We don't have any hidden limits or prices. All pricing, limitations and quotas are clearly stated in our pricing page. Create and use as many mailboxes as you want, as long as you follow our best practices guidelines.

**What support options are available?**
Support is available via documentation, email, and chat. You can reach us at hello@mailapi.tech or via chat on our website.

**Can I create thousands of mailboxes?**
You can create as many mailboxes as you want, as long as you follow our best practices guidelines. You can use multiple domains and subdomains, each with its own mailbox limit.
---

## Public Pages (indexable)

| URL | Purpose |
|-----|---------|
| / | Marketing homepage |
| https://mailapi.tech/pricing | Canonical pricing page |
| https://mailapi.tech/pricing.json | Machine-readable pricing JSON |
| https://mailapi.tech/faq | Canonical FAQ page |
| https://mailapi.tech/help | Help center hub |
| https://mailapi.tech/docs/getting-started | Onboarding guide |
| https://mailapi.tech/docs/inbox-api | Inbox API guide |
| https://mailapi.tech/docs/webhooks | Webhooks guide |
| https://mailapi.tech/docs/dns-verification | DNS verification guide |
| https://mailapi.tech/docs/agent-playbooks | AI agent playbooks |
| https://mailapi.tech/skill.md | Public agent skill file |
| https://mailapi.tech/api/docs | API reference (primary developer doc) |
| https://mailapi.tech/openapi.json | OpenAPI 3.1 specification |
| https://mailapi.tech/llms.txt | Curated LLM index |
| https://mailapi.tech/llms-full.txt | Expanded LLM reference |
| https://mailapi.tech/.well-known/agents.json | Agent discovery manifest |
| https://mailapi.tech/mcp/mailapi | MailAPI MCP server (HTTP) |
| https://mailapi.tech/article | Blog / knowledge base index |
| https://mailapi.tech/article/feed.xml | RSS feed of published articles |
| https://mailapi.tech/article/{slug} | Individual published articles |
| https://mailapi.tech/article/category/{slug} | Category archives |
| https://mailapi.tech/tos | Terms of Service |
| https://mailapi.tech/privacy-policy | Privacy Policy |
| https://mailapi.tech/sitemap.xml | URL discovery |

**Excluded from AI indexing (auth-gated, low citation value)**: `/login`, `/register`, `/dashboard`, `/admin/*`, `/settings/*`, `/domains/*`, `/mailboxes/*`, `/inbox/*`, `/outbound/*`, `/billing/*`, `/tasks/*`, `/check-out`, `/upgrade-plan`

---
## Featured Articles (high citation value)

- https://mailapi.tech/article/how-to-improve-email-deliverability-complete-guide-for-cold-high-volume-sending
- https://mailapi.tech/article/secondary-domains-for-marketing-safe-limits-mailbox-architecture

Additional published posts are listed at https://mailapi.tech/article and in https://mailapi.tech/sitemap.xml

---
## Contact

- Support & privacy inquiries: hello@mailapi.tech
- Website: https://mailapi.tech