---
name: mailapi-agent
description: "Use when integrating with MailAPI (mailapi.tech) to inspect domains and mailboxes, poll provisioning tasks, or orchestrate email infrastructure via API. Covers MCP read/write tools and REST fallback endpoints."
---

# MailAPI Agent Skill

## When to activate

Activate this skill when the user or task involves:

- Listing MailAPI domains or mailboxes
- Polling async domain/mailbox provisioning tasks
- Setting up programmatic email infrastructure on MailAPI
- Configuring an MCP client for MailAPI

## Discovery

| Resource | URL |
|----------|-----|
| Agent manifest | `/.well-known/agents.json` |
| AI plugin manifest | `/.well-known/ai-plugin.json` |
| MCP server | `/mcp/mailapi` |
| Agent playbooks | `/docs/agent-playbooks` |
| OpenAPI | `/openapi.json` |
| Full reference | `/llms-full.txt` |

## Authentication

- Header: `Authorization: Bearer <api_key>` or `X-Api-Key: <api_key>`
- MCP fallback: `api_key` tool argument (32-character key)
- Permissions: `read` (inspect/poll/list emails), `write` (create/delete), `webhook` (register_webhook), `inbound`

## MCP tools

### Read tools

#### list_domains

List all domains for the authenticated tenant.

**Arguments:** `api_key` (optional if header auth works)

**Returns:** `{ total_domain, results: { "example.com": { status, domain_type, domain_quota, mailbox_count, created_at } }, status }`

#### list_mailboxes

List mailboxes on a domain.

**Arguments:** `domain` (required), `include_credentials` (optional), `api_key` (optional)

#### get_task_status

Poll async task status after a create/delete call.

**Arguments:** `task_id` (required), `api_key` (optional)

#### list_emails

List tenant emails with optional filters.

**Arguments:** `mailbox_id`, `unread`, `since`, `before`, `q`, `cursor`, `api_key` (optional)

### Write tools

Require `write` permission and an active plan with API access. All writes are async — poll `get_task_status`.

#### create_domain

**Arguments:** `domain` (required), `total_mailbox_allowed` (optional), `api_key` (optional)

#### create_mailbox

**Arguments:** `domain`, `email_id` (required), `email_fullname`, `password` (use `0` to auto-generate), `api_key` (optional)

#### create_subdomain

**Arguments:** `domain` (required), `sub_domains` (required array, max 10), `api_key` (optional)

#### create_bulk_mailboxes

**Arguments:** `domain`, `mailbox_no` (required), `email_fullname`, `password`, `api_key` (optional)

#### delete_domain

**Arguments:** `domains` (required array), `delete_subdomains` (optional), `api_key` (optional)

#### delete_mailbox

**Arguments:** `mailboxes` (required array of email addresses), `api_key` (optional)

### Webhook tool

#### register_webhook

Requires `webhook` permission.

**Arguments:** `url` (required), `events` (required array), `is_active` (optional), `api_key` (optional)

## MCP resources

- `openapi` — OpenAPI specification URL
- `getting-started` — onboarding markdown
- `dns-verification` — DNS setup markdown
- `inbox-api` — inbox and inbound guide
- `webhooks` — webhook registration guide

## MCP prompts

- `provision-mailbox-workflow` — guided domain + mailbox provisioning steps

## REST operations (when MCP is not enough)

| Operation | Method | Path |
|-----------|--------|------|
| Inbound mail | POST | `/api/v1/mail/inbound` |
| Show email | GET | `/api/v1/emails/{id}` |
| Delete email | DELETE | `/api/v1/emails/{id}` |
| Update webhook | PATCH | `/api/v1/webhooks/{id}` |
| Delete webhook | DELETE | `/api/v1/webhooks/{id}` |

See [OpenAPI](/openapi.json) for request schemas.

## Recommended workflow

1. MCP `list_domains` — check existing infrastructure
2. MCP `create_domain` / `create_mailbox` — enqueue provisioning; returns `task_id`
3. MCP `get_task_status` — poll until `completed` or `failed`
4. MCP `list_mailboxes` — verify mailbox exists
5. MCP `list_emails` / `register_webhook` — inbox automation as needed

Full playbook: [/docs/agent-playbooks](/docs/agent-playbooks)

## Cursor MCP config

```json
{
  "mcpServers": {
    "mailapi": {
      "url": "https://mailapi.tech/mcp/mailapi",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```