{ "openapi": "3.0.3", "info": { "title": "Icemail API", "description": "## Introduction\n\nThe Icemail API provides programmatic access to manage your email infrastructure — domains, mailboxes, DNS records, workspaces, and billing.\n\n---\n\n### Getting Started\n\n**Step 1 — Obtain your API Key**\n\nLog into your [Icemail Dashboard](https://icemail.ai), navigate to **Settings > API Keys**, and click **Generate New Key**.\n\n> **Important:** Keep your API key secret. Never expose it in frontend code or public repositories.\n\n**Step 2 — Make your first request**\n\nVerify your API key by listing your workspaces:\n\n```bash\ncurl -X GET https://app.icemail.ai/api/v1/workspace \\\n -H \"x-api-key: YOUR_API_KEY\"\n```\n\nA successful response will return `200` with your workspace data.\n\n---\n\n### Authentication\n\nAll requests require your API key in the `x-api-key` header:\n\n```\nx-api-key: YOUR_API_KEY\n```\n\nRequests without a valid key will return `403 Forbidden`.\n\n---\n\n### Base URL\n\n```\nhttps://app.icemail.ai/api/v1\n```\n\n---\n\n### Pagination\n\nAll list endpoints support pagination:\n\n| Parameter | Default | Max | Description |\n|---|---|---|---|\n| `page` | 1 | — | Page number |\n| `limit` | 10 | 50 | Items per page |\n| `search` | — | — | Filter results (varies by endpoint) |\n\n**Example:** `GET /domain?page=2&limit=5&search=example`\n\n---\n\n### Roles & Permissions\n\nIcemail uses role-based access control (RBAC). Each workspace member is assigned one of the following roles:\n\n| Role | Description |\n|---|---|\n| **OWNER** | Full access — manage billing, invite users, and modify all resources. |\n| **ADMIN** | Same as Owner, except cannot delete the workspace. |\n| **EDITOR** | Manage domains, DNS, mailboxes, and forwarding. Cannot modify billing or invite users. |\n| **VIEWER** | Read-only access to all resources. |\n\nPermission requirements are noted on each endpoint below.\n\n---\n\n### Response Format\n\nAll endpoints return a consistent JSON structure:\n\n**Success (200 / 201)**\n```json\n{\n \"success\": true,\n \"data\": { ... },\n \"message\": \"Operation completed successfully\"\n}\n```\n\n**Error (4xx)**\n```json\n{\n \"success\": false,\n \"message\": \"Description of what went wrong\",\n \"errors\": [{ \"field\": \"name\", \"message\": \"name is required\" }]\n}\n```\n\n---\n\n### Error Codes\n\n| Code | Meaning | Common Cause |\n|---|---|---|\n| `400` | Bad Request | Missing required fields or invalid data |\n| `403` | Forbidden | Invalid API key or insufficient permissions |\n| `404` | Not Found | Resource ID does not exist |\n| `409` | Conflict | Duplicate entry (e.g. user already invited) |\n\n---\n\n### Rate Limiting\n\nAll v1 API endpoints are rate-limited using a **dual-window** system (burst + sustained) to prevent abuse while allowing normal usage patterns.\n\n#### Default Limits\n\n| Endpoint Pattern | Burst (per second) | Sustained (per minute) |\n|---|---|---|\n| `POST /v1/export` | 1 req/s | 1 req/day (per mailbox, per vendor — unlimited for `sequencer: other`) |\n| `GET /v1/export/:id` | 5 req/s | 30 req/min |\n| `GET /v1/mailbox/:id/auth` | 5 req/s | 30 req/min |\n| `PUT /v1/mailbox/*` | 5 req/s | 20 req/min |\n| `* /v1/domain/:id/dns-records` | 5 req/s | 20 req/min |\n| `PUT,DELETE /v1/domain/forwarding,dmarc` | 1 req/s | 10 req/min |\n| `POST /v1/order` | 1 req/5s | 12 req/min |\n| `POST /v1/wallet/topup` | 1 req/10s | 20 req/min |\n| `POST /v1/prewarm/buy` | 1 req/5s | 12 req/min |\n| `* /v1/prewarm*` | 5 req/s | 30 req/min |\n| `* /v1/domain*` | 5 req/s | 30 req/min |\n| `* /v1/mailbox*` | 5 req/s | 30 req/min |\n| All other endpoints | 5 req/s | 30 req/min |\n\n#### Entity-Scoped Limits\n\n`POST /v1/export` is rate-limited **per mailbox_id, per destination vendor (`sequencer`), per day**. Each mailbox in `mailbox_ids` consumes a separate rate limit point, keyed to the `sequencer` in the request — so a mailbox already exported today to `instantly` can still be exported today to `smartlead`. Exports with `sequencer: \"other\"` are exempt from this limit entirely.\n\nOnly an accepted export (`201`) counts. A request refused with `429`, or one that fails, uses no quota. The window is a rolling 24 hours from the accepted export. If any mailbox in `mailbox_ids` is over its limit, the whole request is refused and nothing is exported. A repeated mailbox ID is counted once.\n\n#### Response Headers\n\nEvery response includes rate limit headers based on the sustained (per-minute) window:\n\n```\nX-RateLimit-Limit: 30\nX-RateLimit-Remaining: 25\nX-RateLimit-Reset: 1700000060\n```\n\n#### Rate Limit Exceeded (429)\n\nWhen rate limited, a `Retry-After` header is also included:\n\n```\nRetry-After: 60\n```\n\n```json\n{\n \\\"success\\\": false,\n \\\"message\\\": \\\"Too many requests. Please try again later.\\\",\n \\\"retry_after\\\": 60\n}\n```\n\nFor `POST /v1/export`, the body also includes `blocked`: the ID of every mailbox in `mailbox_ids` that is over its limit. `Retry-After` is the number of seconds until the first blocked mailbox can be exported again (up to `86400`). Don't resend the same batch on a fixed timer: remove the `blocked` IDs, wait 1–2 seconds (resending a mailbox within 1 second hits the burst limit), and resend the rest.\n\n---\n\n### Permission Matrix\n\n| Endpoint | OWNER | ADMIN | EDITOR | VIEWER |\n|---|---|---|---|---|\n| GET /v1/workspace | Yes | Yes | Yes | Yes |\n| POST /v1/workspace | Yes | Yes | No | No |\n| PUT /v1/workspace | Yes | Yes | No | No |\n| POST /v1/workspace/invite | Yes | Yes | No | No |\n| GET /v1/wallet | Yes | Yes | Yes | Yes |\n| PUT /v1/wallet/auto-topup | Yes | Yes | No | No |\n| POST /v1/wallet/topup | Yes | Yes | No | No |\n| GET /v1/domain | Yes | Yes | Yes | Yes |\n| GET /v1/domain/available | Yes | Yes | Yes | Yes |\n| GET /v1/domain/:id | Yes | Yes | Yes | Yes |\n| GET /v1/domain/ns-records | Yes | Yes | Yes | Yes |\n| GET /v1/domain/:id/dns-records | Yes | Yes | Yes | Yes |\n| POST /v1/domain/:id/dns-records | Yes | Yes | Yes | No |\n| PUT /v1/domain/:id/dns-records | Yes | Yes | Yes | No |\n| PUT /v1/domain/:id/forwarding | Yes | Yes | Yes | No |\n| PUT /v1/domain/:id/dmarc | Yes | Yes | Yes | No |\n| PUT /v1/domain/forwarding | Yes | Yes | Yes | No |\n| PUT /v1/domain/dmarc | Yes | Yes | Yes | No |\n| POST /v1/domain/add-google-client-id | Yes | Yes | Yes | No |\n| DELETE /v1/domain/forwarding | Yes | Yes | Yes | No |\n| DELETE /v1/domain/dmarc | Yes | Yes | Yes | No |\n| DELETE /v1/domain/mailboxes | Yes | Yes | Yes | No |\n| DELETE /v1/domain/clear-dns | Yes | Yes | Yes | No |\n| DELETE /v1/domain | Yes | Yes | Yes | No |\n| GET /v1/mailbox | Yes | Yes | Yes | Yes |\n| GET /v1/mailbox/:id | Yes | Yes | Yes | Yes |\n| GET /v1/mailbox/domain/:id | Yes | Yes | Yes | Yes |\n| GET /v1/mailbox/price | Yes | Yes | Yes | Yes |\n| PUT /v1/mailbox/:id | Yes | Yes | Yes | No |\n| PUT /v1/mailbox/forwarding | Yes | Yes | Yes | No |\n| DELETE /v1/mailbox/forwarding | Yes | Yes | Yes | No |\n| GET /v1/mailbox/:id/auth | Yes | Yes | Yes | Yes |\n| GET /v1/mailbox/:id/app-password | Yes | Yes | Yes | Yes |\n| POST /v1/order | Yes | Yes | Yes | No |\n| GET /v1/prewarm | Yes | Yes | Yes | Yes |\n| POST /v1/prewarm/buy | Yes | Yes | Yes | No |\n| POST /v1/export | Yes | Yes | Yes | No |\n| GET /v1/export/:id | Yes | Yes | Yes | Yes |\n| POST /v1/export/republish/:id | Yes | Yes | Yes | No |\n| POST /v1/lookup/mailboxes | Yes | Yes | Yes | Yes |\n| POST /v1/lookup/domains | Yes | Yes | Yes | Yes |\n| GET /v1/webhook | Yes | Yes | Yes | Yes |\n| POST /v1/webhook | Yes | Yes | No | No |\n| PUT /v1/webhook/:id | Yes | Yes | No | No |\n| DELETE /v1/webhook/:id | Yes | Yes | No | No |\n\n---\n\n### Support\n\nVisit [icemail.ai](https://icemail.ai) or contact our support team for assistance.\n", "version": "1.0.0", "contact": { "name": "Icemail Support", "url": "https://icemail.ai", "email": "support@icemail.ai" } }, "externalDocs": { "description": "Icemail Dashboard", "url": "https://icemail.ai" }, "servers": [ { "url": "https://app.icemail.ai/api/v1", "description": "Use https://app.icemail.ai/api/v1 for Icemail users, and for whitelabel customers, use the respective whitelabel URL provided by Icemail." } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Workspace", "description": "Workspaces are the top-level container in Icemail. All domains, mailboxes, and billing are scoped to a workspace.\n\nUse these endpoints to create and update workspaces, and to invite team members with role-based access." }, { "name": "Wallet", "description": "The wallet manages your workspace's credit balance and auto top-up configuration.\n\nCredits are consumed when provisioning domains, mailboxes, and other billable resources." }, { "name": "Domain", "description": "Domains are the foundation of your email infrastructure. Each domain supports DNS records, URL forwarding, and DMARC policies.\n\nBulk endpoints are available for applying forwarding and DMARC settings across multiple domains simultaneously.\n\n### Domain Termination Flow\n\nWinding a domain down is a three-stage process. Each stage has its own endpoint; pick the stage that matches what you want to do.\n\n| Stage | Endpoint | What it ends | What survives |\n|---|---|---|---|\n| 1. Delete Mailboxes | `DELETE /domain/mailboxes` | Every mailbox on the domain | The domain row + its DNS zone (records may stay too) |\n| 2. Clear DNS Records | `DELETE /domain/clear-dns` | All MX / SPF / DKIM / DMARC / forwarding records | The zone itself + the Domains row — ready to reuse |\n| 3. Delete Domains | `DELETE /domain` | The Domains row + ClouDNS zone + leftover inactive mailbox history | Nothing — the domain is removed from your listing (permanent) |\n\n**Common flows:**\n\n- **Wind down everything permanently** → `DELETE /domain/mailboxes` (immediate) → wait for vendor cleanup → `DELETE /domain`.\n- **Reuse the domain for a fresh mailbox batch** → `DELETE /domain/mailboxes` (immediate) → `DELETE /domain/clear-dns`. Domain stays in your listing, zone is empty and ready.\n- **Stop paying at the end of the current cycle** → `DELETE /domain/mailboxes` with `mode: \"scheduled\"`. Mailboxes keep working until their billing date, then auto-delete.\n\nEach endpoint enforces preconditions and **silently skips** domains that don't qualify (rather than erroring the whole batch) — call the missing stage first and retry." }, { "name": "Mailbox", "description": "Mailboxes represent individual email accounts associated with your domains (e.g. `john@yourdomain.com`).\n\nEach mailbox can be configured with forwarding rules and supports 2FA authenticator code retrieval." }, { "name": "Order", "description": "Orders allow you to purchase new domains or import existing ones, and provision mailboxes — all in a single request.\n\nCredits are deducted for each domain and mailbox created. Importing existing domains skips the domain charge." }, { "name": "Pre-Warm", "description": "Pre-warm domains to improve email deliverability before sending campaigns.\n\nList and monitor domains that are in the pre-warming phase." }, { "name": "Export", "description": "Export mailboxes directly to supported cold email sequencers (Instantly, Smartlead, Reachinbox, Emailbison, Plusvibe, Masterinbox, Salesforge, Sendkit, OutreachFox), or to an unlisted platform via `other`.\n\nEach export is rate-limited per mailbox, per vendor, per day to prevent abuse — exports with `sequencer: \"other\"` are unlimited." }, { "name": "Lookup", "description": "Resolve human-readable identifiers to Icemail resource IDs in bulk.\n\nMap usernames to mailbox IDs and domain names to domain IDs so you can reference resources by name without listing them first. Unknown names resolve to `null`." }, { "name": "Webhooks", "description": "## Overview\n\nA webhook is an HTTP POST request that is automatically sent to your configured URL when a specific event occurs. Instead of polling the API for updates, webhooks push real-time data to your application the moment something happens.\n\n## Setting Up Webhooks\n\nTo configure a webhook, navigate to **Settings > Notification > Add Webhook URL** in the dashboard.\n\nYou will need to provide:\n- **URL** — The HTTPS endpoint on your server that will receive webhook events\n- **Description** (optional) — A label to identify the webhook\n\n## Retry Behavior\n\nIf your endpoint returns a non-2xx status code or times out (10 seconds), the delivery is retried up to **5 times** with exponential backoff (30s, 60s, 120s, 240s, 480s). You can view delivery history and debug failures from **Settings > Notification > Delivery Logs**.\n\n## Controlling Which Events Fire\n\n| Event |\n|---|\n| `order.mailbox.active` |\n| `order.mailbox.failed` |\n| `order.domain.active` |\n| `order.domain.failed` |\n| `order.export.completed` |\n| `order.mailbox.deleted` |\n| `order.mailbox.renewed` |\n| `mailbox.renewal.reminder` |\n| `domain.renewal.reminder` |\n| `mailbox.app_password.updated` |\n| `order.client_id.completed` |\n| `order.client_id.failed` |\n\n---\n\n## Managing Webhooks via the API\n\nIn addition to the dashboard, webhook endpoints can be fully managed via the API:\n\n| Method | Endpoint | Required Role |\n|---|---|---|\n| `POST` | `/webhook` | OWNER, ADMIN |\n| `GET` | `/webhook` | OWNER, ADMIN, EDITOR, VIEWER |\n| `PUT` | `/webhook/{id}` | OWNER, ADMIN |\n| `DELETE` | `/webhook/{id}` | OWNER, ADMIN |\n\n- Omitting `subscribed_events` (or passing `[]`) subscribes the endpoint to **all events** — this is the default.\n- `subscribed_events` accepts raw event ids directly, e.g. `[\"order.mailbox.active\", \"order.mailbox.failed\"]`.\n- Maximum of **5** webhook endpoints per workspace.\n\n---\n\n## Webhook Events\n\nEvery delivery uses the same envelope: `event`, `timestamp`, `workspace_id`, `email` (the workspace owner's email, resolved at dispatch time), and `data` (event-specific payload).\n\n### 1. Mailbox Active (`order.mailbox.active`)\n\nTriggered when **all mailboxes** in an order have been successfully created and are now active.\n\n**Trigger condition:** Every mailbox in the order reaches `ACTIVE` status.\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.mailbox.active\",\n \"timestamp\": \"2026-04-17T10:30:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"mailbox_count\": 3,\n \"mailboxes\": [\n { \"mailbox_id\": \"01JF8XA1B2C3D4E5F6G7H8J9K0\", \"username\": \"john@example.com\" },\n { \"mailbox_id\": \"01JF8XA2B3C4D5E6F7G8H9J0K1\", \"username\": \"jane@example.com\" },\n { \"mailbox_id\": \"01JF8XA3B4C5D6E7F8G9H0J1K2\", \"username\": \"mike@example.com\" }\n ]\n }\n}\n```\n\n### 2. Mailbox Failed (`order.mailbox.failed`)\n\nTriggered when a mailbox creation fails during the provisioning process.\n\n**Trigger condition:** A mailbox fails to be created by the vendor (Google, Microsoft, or Custom).\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.mailbox.failed\",\n \"timestamp\": \"2026-04-17T10:35:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"failed_mailboxes\": [\n {\n \"mailbox_id\": \"01JF8XA4B5C6D7E8F9G0H1J2K3\",\n \"username\": \"alex@example.com\",\n \"error_message\": \"Mailbox creation failed: license limit reached\",\n \"error_code\": \"LICENSE_LIMIT\"\n }\n ]\n }\n}\n```\n\n### 3. Domain Active (`order.domain.active`)\n\nTriggered when **all domains** in an order have been activated and DNS propagation is complete.\n\n**Trigger condition:** Every domain in the order reaches `ACTIVE` status after nameserver verification.\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.domain.active\",\n \"timestamp\": \"2026-04-17T11:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"domain_count\": 2,\n \"domains\": [\n { \"domain_id\": \"01JF8XB1C2D3E4F5G6H7J8K9L0\", \"domain\": \"example.com\" },\n { \"domain_id\": \"01JF8XB2C3D4E5F6G7H8J9K0L1\", \"domain\": \"example.io\" }\n ]\n }\n}\n```\n\n### 4. Domain Failed (`order.domain.failed`)\n\nTriggered when one or more domain purchases or setups fail.\n\n**Trigger condition:** A domain fails during purchase, DNS zone creation, or nameserver propagation.\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.domain.failed\",\n \"timestamp\": \"2026-04-17T11:05:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"failed_domains\": [\n {\n \"domain_id\": \"01JF8XB3C4D5E6F7G8H9J0K1L2\",\n \"domain\": \"example.net\",\n \"error_message\": \"Domain purchase failed: payment declined\"\n },\n {\n \"domain_id\": \"01JF8XB4C5D6E7F8G9H0J1K2L3\",\n \"domain\": \"example.org\",\n \"error_message\": \"DNS zone creation failed: domain already exists\"\n }\n ]\n }\n}\n```\n\n### 5. Export Completed (`order.export.completed`)\n\nTriggered when all mailbox export jobs for an order have finished processing. The payload splits mailboxes into successfully exported, failed, and pending (jobs that never reached a terminal state).\n\n**Trigger condition:** All export jobs for the order have finished processing and no auto-retry is pending. Jobs that never resolved are still reported, in `pending_mailboxes`.\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.export.completed\",\n \"timestamp\": \"2026-04-17T12:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"export_id\": \"01JF8XC1D2E3F4G5H6J7K8L9M0\",\n \"total\": 4,\n \"failed_count\": 1,\n \"completed_mailboxes\": [\n { \"mailbox_id\": \"01JF8XA1B2C3D4E5F6G7H8J9K0\", \"username\": \"john@example.com\" },\n { \"mailbox_id\": \"01JF8XA2B3C4D5E6F7G8H9J0K1\", \"username\": \"jane@example.com\" }\n ],\n \"failed_mailboxes\": [\n { \"mailbox_id\": \"01JF8XA3B4C5D6E7F8G9H0J1K2\", \"username\": \"mike@example.com\", \"error_message\": \"Export job failed: vendor rejected credentials\" }\n ],\n \"pending_mailboxes\": [\n { \"mailbox_id\": \"01JF8XA4B5C6D7E8F9G0H1J2K3\", \"username\": \"alex@example.com\" }\n ]\n }\n}\n```\n\n> **Fields:** `total` is the number of mailboxes in the export; `failed_count` is the number of failed jobs. `completed_mailboxes` + `failed_mailboxes` + `pending_mailboxes` together account for `total`. Failed entries include an `error_message`; `pending_mailboxes` contains jobs that never reached a terminal state.\n\n### 6. Mailbox Deleted (`order.mailbox.deleted`)\n\nTriggered when one or more mailboxes are deleted from a workspace.\n\n**Trigger condition:** Mailboxes are deleted via the dashboard or API. Includes cascading deletions (e.g. deleting a Google admin master mailbox also deletes dependent mailboxes on the same domain).\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.mailbox.deleted\",\n \"timestamp\": \"2026-04-17T14:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"deleted_count\": 2,\n \"mailboxes\": [\n { \"mailbox_id\": \"01JF8XA1B2C3D4E5F6G7H8J9K0\", \"username\": \"john@example.com\" },\n { \"mailbox_id\": \"01JF8XA2B3C4D5E6F7G8H9J0K1\", \"username\": \"jane@example.com\" }\n ]\n }\n}\n```\n\n### 7. Domain Renewal Reminder (`domain.renewal.reminder`)\n\nTriggered 30 days before a domain's registration expires as a reminder to renew.\n\n**Trigger condition:** A daily check identifies domains where the creation date plus the license duration is within 30 days. Only applies to domains that are not imported (`import = false`) and not Cloudflare-managed (`cf_app_id` is null).\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"domain.renewal.reminder\",\n \"timestamp\": \"2026-04-17T04:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"domain_id\": \"01JF8XB1C2D3E4F5G6H7J8K9L0\",\n \"domain\": \"example.com\",\n \"created_at\": \"2025-05-17T00:00:00.000Z\",\n \"expires_at\": \"2026-05-17T00:00:00.000Z\",\n \"days_until_expiry\": 30\n }\n}\n```\n\n### 8. App Password Updated (`mailbox.app_password.updated`)\n\nTriggered whenever a mailbox's app password is set or updated.\n\n**Trigger condition:** Fires when an app password is written via the internal provisioning callback (app-password setup completing for a Google mailbox).\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"mailbox.app_password.updated\",\n \"timestamp\": \"2026-04-17T15:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"mailbox_id\": \"01JF8XA1B2C3D4E5F6G7H8J9K0\",\n \"username\": \"john@example.com\",\n \"app_password\": \"abcd efgh ijkl mnop\"\n }\n}\n```\n\n> **Security note:** `app_password` is the plaintext app password. Only endpoints you trust should be subscribed to this event.\n\n### 9. Google Client ID Completed (`order.client_id.completed`)\n\nTriggered when a Google OAuth client ID pushed via `POST /domain/add-google-client-id` has been added to a domain's master inbox.\n\n**Trigger condition:** One event per master inbox queued by the request, once its setup succeeds.\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.client_id.completed\",\n \"timestamp\": \"2026-04-17T16:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"domain_id\": \"01JF8XB1C2D3E4F5G6H7J8K9L0\",\n \"domain\": \"example.com\"\n }\n}\n```\n\n### 10. Google Client ID Failed (`order.client_id.failed`)\n\nTriggered when pushing a Google OAuth client ID via `POST /domain/add-google-client-id` fails for a domain's master inbox.\n\n**Trigger condition:** One event per master inbox queued by the request, if its setup fails.\n\n**Sample Payload:**\n\n```json\n{\n \"event\": \"order.client_id.failed\",\n \"timestamp\": \"2026-04-17T16:00:00.000Z\",\n \"workspace_id\": \"ws_abc123\",\n \"email\": \"owner@example.com\",\n \"data\": {\n \"domain_id\": \"01JF8XB1C2D3E4F5G6H7J8K9L0\",\n \"domain\": \"example.com\",\n \"error_message\": \"Client ID setup failed\"\n }\n}\n```" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Icemail API key. Generate one from **Dashboard > Settings > API Keys**." } }, "schemas": { "SuccessResponse": { "type": "object", "description": "Standard success response.", "properties": { "success": { "type": "boolean", "example": true, "description": "Always `true` for successful requests." }, "data": { "type": "object", "description": "Response payload. Structure varies by endpoint." }, "message": { "type": "string", "example": "Operation completed successfully", "description": "Human-readable status message." } } }, "ValidationError": { "type": "object", "description": "Returned when the request body or query parameters fail validation.", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "array", "description": "Field-level validation errors.", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "name", "description": "The field that failed validation." }, "message": { "type": "string", "example": "name is required", "description": "Description of the validation failure." } } } } } }, "PermissionError": { "type": "object", "description": "Returned when the API key lacks the required role.", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You don't have permission to perform this action" } } }, "NotFoundError": { "type": "object", "description": "Returned when the specified resource does not exist.", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Resource not found" } } }, "ConflictError": { "type": "object", "description": "Returned when the operation would create a duplicate entry.", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Already a member of this workspace" } } }, "Workspace": { "type": "object", "description": "A workspace — the top-level organizational unit in Icemail.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique workspace identifier.", "example": "ws_a1b2c3d4" }, "name": { "type": "string", "description": "Display name of the workspace.", "example": "My Company" } } }, "Wallet": { "type": "object", "description": "Workspace billing wallet with balance and auto top-up settings.", "properties": { "balance": { "type": "number", "description": "Current balance in account currency.", "example": 125.5 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "auto_topup": { "type": "object", "description": "When enabled, the wallet is recharged automatically when balance drops below the threshold.", "properties": { "enabled": { "type": "boolean", "description": "Whether auto top-up is active.", "example": true }, "threshold": { "type": "number", "description": "Balance threshold that triggers a top-up.", "example": 10 }, "topup_amount": { "type": "number", "description": "Amount added per top-up.", "example": 50 } } } } }, "Domain": { "type": "object", "description": "A domain registered in your workspace.", "properties": { "domain_id": { "type": "string", "description": "Unique domain identifier.", "example": "01DEF..." }, "domain": { "type": "string", "description": "Domain name.", "example": "example.com" }, "status": { "type": "string", "description": "Current status (e.g. `ACTIVE`, `PENDING`).", "example": "ACTIVE" }, "created_at": { "type": "string", "format": "date-time", "description": "When the domain was created.", "example": "2026-04-27T10:00:00.000Z" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Domain registration expiry date. `null` for domains with no expiry set (e.g. some imported/connected domains).", "example": "2027-04-27T10:00:00.000Z" }, "import": { "type": "boolean", "description": "Whether the domain was imported (vs. purchased through Icemail).", "example": false }, "order_id": { "type": "string", "description": "Identifier of the order that created this domain.", "example": "01ABC..." }, "mailbox_count": { "type": "integer", "description": "Number of mailboxes on this domain.", "example": 3 }, "domain_forwarding": { "type": "boolean", "description": "Whether domain forwarding is enabled.", "example": false }, "domain_forwarding_url": { "type": "string", "description": "Forwarding destination URL. Empty string when not configured.", "example": "" }, "dmarc_email": { "type": "string", "description": "DMARC report recipient. Empty string when not configured.", "example": "" }, "dmarc": { "type": "boolean", "description": "Whether a DMARC record is present.", "example": true }, "forwarding": { "type": "boolean", "description": "Whether forwarding is configured.", "example": false }, "spf": { "type": "boolean", "description": "Whether the SPF record is present.", "example": true }, "dkim": { "type": "boolean", "description": "Whether the DKIM record is present.", "example": true }, "mx_records": { "type": "boolean", "description": "Whether MX records are present.", "example": true }, "active": { "type": "boolean", "description": "Whether the domain is active.", "example": true }, "workspace_type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT" ], "description": "Email provider associated with the domain.", "example": "GOOGLE" }, "cf_app_id": { "type": "string", "nullable": true, "description": "Cloudflare app identifier, or `null` if the domain is not Cloudflare-managed.", "example": null }, "prewarmed": { "type": "boolean", "description": "Whether the domain came from the pre-warm pool.", "example": false }, "associate_with_google": { "type": "boolean", "description": "Whether the domain is associated with Google Workspace.", "example": true }, "associate_with_microsoft": { "type": "boolean", "description": "Whether the domain is associated with Microsoft 365.", "example": false }, "blacklisted": { "type": "boolean", "description": "Whether the domain is blacklisted.", "example": false } } }, "DnsRecord": { "type": "object", "description": "A DNS record associated with a domain.", "properties": { "id": { "type": "string", "description": "Record identifier. Required when updating.", "example": "rec_001" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "PTR", "HTTPS", "SVCB", "TLSA", "CAA" ], "description": "DNS record type." }, "name": { "type": "string", "description": "Record name. Use `@` for root domain.", "example": "@" }, "content": { "type": "string", "description": "Record value (IP, hostname, or text depending on type).", "example": "1.2.3.4" } } }, "Mailbox": { "type": "object", "description": "An email mailbox (e.g. `john@yourdomain.com`). Returned by `GET /mailbox` and `GET /mailbox/{id}`.", "properties": { "id": { "type": "string", "description": "Unique mailbox identifier.", "example": "01GHI..." }, "first_name": { "type": "string", "description": "Owner's first name.", "example": "John" }, "last_name": { "type": "string", "description": "Owner's last name.", "example": "Doe" }, "username": { "type": "string", "description": "Full email address.", "example": "john@example.com" }, "recovery_email": { "type": "string", "nullable": true, "description": "Recovery email address.", "example": "john.recovery@gmail.com" }, "forward_email": { "type": "string", "nullable": true, "description": "Address that incoming mail is forwarded to.", "example": "john.fwd@gmail.com" }, "type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT", "CUSTOM" ], "description": "`GOOGLE` — Google Workspace, `MICROSOFT` — Microsoft 365, `CUSTOM` — Custom SMTP/IMAP.", "example": "GOOGLE" }, "status": { "type": "string", "description": "Current status (e.g. `ACTIVE`, `UPDATING`).", "example": "ACTIVE" }, "active": { "type": "boolean", "description": "Whether the mailbox is active.", "example": true }, "master_inbox": { "type": "boolean", "description": "Whether this is the master (admin) inbox for its domain.", "example": false }, "created_at": { "type": "string", "format": "date-time", "description": "When the mailbox was created.", "example": "2026-04-27T10:00:00.000Z" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the mailbox was last modified.", "example": "2026-04-27T10:00:00.000Z" }, "password": { "type": "string", "nullable": true, "description": "Mailbox password, returned as decrypted plaintext. `null` for mailboxes without a stored password (e.g. OAuth-only). Treat the response as sensitive and avoid logging.", "example": "Plaintext" }, "domains": { "type": "object", "description": "The domain this mailbox belongs to.", "properties": { "domain_id": { "type": "string", "description": "Domain identifier.", "example": "01DEF..." }, "domain": { "type": "string", "description": "Domain name.", "example": "example.com" } } }, "next_billing_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Next billing date from the mailbox's purchase record. `null` when no purchase exists.", "example": "2026-05-27T10:00:00.000Z" }, "cost": { "type": "string", "nullable": true, "description": "Per-unit price as a decimal string (trailing zeros stripped, e.g. `\"4.9\"`). `null` when no purchase exists.", "example": "4.99" }, "billing_cycle": { "type": "string", "enum": [ "MONTHLY", "YEARLY" ], "nullable": true, "description": "Billing cycle from the purchase record. `null` when no purchase exists.", "example": "MONTHLY" } } }, "DomainMailbox": { "type": "object", "description": "Reduced mailbox shape returned by `GET /mailbox/domain/{domainId}`. Does not include `password`, the nested `domains` object, or billing fields; adds `warmup_duration`.", "properties": { "id": { "type": "string", "description": "Unique mailbox identifier.", "example": "01GHI..." }, "first_name": { "type": "string", "description": "Owner's first name.", "example": "John" }, "last_name": { "type": "string", "description": "Owner's last name.", "example": "Doe" }, "username": { "type": "string", "description": "Full email address.", "example": "john@example.com" }, "recovery_email": { "type": "string", "nullable": true, "description": "Recovery email address.", "example": "john.recovery@gmail.com" }, "forward_email": { "type": "string", "nullable": true, "description": "Address that incoming mail is forwarded to.", "example": "john.fwd@gmail.com" }, "type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT", "CUSTOM" ], "description": "Email provider.", "example": "GOOGLE" }, "warmup_duration": { "type": "integer", "description": "Warm-up period in days.", "example": 14 }, "created_at": { "type": "string", "format": "date-time", "description": "When the mailbox was created.", "example": "2026-04-27T10:00:00.000Z" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the mailbox was last modified.", "example": "2026-04-27T10:00:00.000Z" }, "active": { "type": "boolean", "description": "Whether the mailbox is active.", "example": true }, "status": { "type": "string", "description": "Current status (e.g. `ACTIVE`).", "example": "ACTIVE" }, "domain_id": { "type": "string", "description": "Identifier of the domain this mailbox belongs to.", "example": "01DEF..." }, "master_inbox": { "type": "boolean", "description": "Whether this is the master (admin) inbox for its domain.", "example": false } } }, "UpdatedMailbox": { "type": "object", "description": "A mailbox entry returned by the update endpoints. The update is queued to the vendor, so `status` is `UPDATING`.", "properties": { "id": { "type": "string", "description": "Unique mailbox identifier.", "example": "01GHI..." }, "first_name": { "type": "string", "description": "Owner's first name.", "example": "John" }, "last_name": { "type": "string", "description": "Owner's last name.", "example": "Doe" }, "username": { "type": "string", "description": "Full email address.", "example": "johndoe@example.com" }, "recovery_email": { "type": "string", "nullable": true, "description": "Recovery email address.", "example": "john.recovery@gmail.com" }, "forward_email": { "type": "string", "nullable": true, "description": "Address that incoming mail is forwarded to.", "example": "john.fwd@gmail.com" }, "type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT", "CUSTOM" ], "description": "Email provider.", "example": "GOOGLE" }, "warmup_duration": { "type": "integer", "description": "Warm-up period in days.", "example": 14 }, "created_at": { "type": "string", "format": "date-time", "description": "When the mailbox was created.", "example": "2026-04-27T10:00:00.000Z" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the mailbox was last modified.", "example": "2026-04-27T10:05:00.000Z" }, "active": { "type": "boolean", "description": "Whether the mailbox is active.", "example": true }, "status": { "type": "string", "description": "Current status. `UPDATING` while the change is queued to the vendor.", "example": "UPDATING" }, "domain_id": { "type": "string", "description": "Identifier of the domain this mailbox belongs to.", "example": "01DEF..." }, "admin": { "type": "boolean", "description": "Whether this mailbox is an admin.", "example": false }, "cycle_intervel": { "type": "integer", "description": "Billing cycle interval.", "example": 0 }, "old_username": { "type": "string", "description": "Previous username. Present only when the username changed.", "example": "john@example.com" }, "old_forward_email": { "type": "string", "description": "Previous forwarding email. Present only when the forwarding email changed.", "example": "old.fwd@gmail.com" } } }, "MailboxUpdateResult": { "type": "object", "description": "Result of `PUT /mailbox/{id}` and `PUT /mailbox/forwarding`. Contains one entry per requested mailbox.", "properties": { "updated_mailboxes": { "type": "array", "description": "Mailboxes that were successfully queued for update.", "items": { "$ref": "#/components/schemas/UpdatedMailbox" } }, "failed_updates": { "type": "array", "description": "Entries that failed validation.", "items": { "type": "object" } }, "summary": { "type": "object", "properties": { "total_requested": { "type": "integer", "description": "Number of mailboxes in the request.", "example": 1 }, "successful": { "type": "integer", "description": "Number of mailboxes successfully queued.", "example": 1 }, "failed": { "type": "integer", "description": "Number of mailboxes that failed.", "example": 0 } } } } }, "AuthCode": { "type": "object", "nullable": true, "description": "Current 2FA TOTP code. Returns `null` if 2FA is not configured on the mailbox.", "properties": { "token": { "type": "string", "description": "Current 6-digit TOTP code.", "example": "482913" }, "remaining": { "type": "integer", "description": "Seconds until this code expires.", "example": 22 } } }, "BundlePlan": { "type": "object", "description": "A bundle-priced mailbox plan (CUSTOM, AZURE). `price` is the flat cost for the whole pack; individual mailbox prices within a pack are derived from `price` / `mailbox_limit`.", "properties": { "mailbox_limit": { "type": "integer", "description": "Number of mailboxes included in this plan.", "example": 30 }, "domain_limit": { "type": "integer", "description": "Number of domains this plan can span.", "example": 2 }, "mailbox_per_domain": { "type": "integer", "description": "Max mailboxes allowed per domain under this plan.", "example": 15 }, "price": { "type": "number", "description": "Flat price for one pack of this plan.", "example": 49 } } }, "MailboxPricing": { "type": "object", "description": "Resolved mailbox pricing for the calling workspace — reflects any active pricing override, falling back to the tenant/plan default otherwise.", "properties": { "direct": { "type": "object", "description": "Per-mailbox price, at the only variant each provider is sold at (Google: admin panel, Microsoft: standard).", "properties": { "GOOGLE": { "type": "number", "description": "Per-mailbox monthly price for Google Workspace.", "example": 5.0 }, "MICROSOFT": { "type": "number", "description": "Per-mailbox monthly price for Microsoft 365.", "example": 4.0 } } }, "bundles": { "type": "object", "description": "Bundle-wise plan pricing, keyed by plan type.", "properties": { "CUSTOM": { "type": "object", "description": "CUSTOM plans, keyed by plan type (e.g. `STARTER`, `GROWTH`, `PRO`).", "additionalProperties": { "$ref": "#/components/schemas/BundlePlan" } }, "AZURE": { "type": "object", "description": "AZURE plans, keyed by plan type (e.g. `BASIC`).", "additionalProperties": { "$ref": "#/components/schemas/BundlePlan" } } } } } } }, "responses": { "400": { "description": "Bad Request — Missing required fields or invalid data. See `errors` array for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "403": { "description": "Forbidden — Invalid API key or insufficient role permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionError" } } } }, "404": { "description": "Not Found — The specified resource ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "409": { "description": "Conflict — A duplicate entry already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } } }, "parameters": { "page": { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number (starts at 1)." }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 }, "description": "Items per page (max 50)." } } }, "paths": { "/workspace": { "get": { "tags": [ "Workspace" ], "summary": "List Workspaces", "description": "Returns all workspaces accessible by the authenticated API key.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "listWorkspaces", "responses": { "200": { "description": "List of workspaces.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } }, "example": { "success": true, "data": [ { "id": "ws_a1b2c3d4", "name": "My Company" }, { "id": "ws_e5f6g7h8", "name": "Client Project" } ] } } } }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "tags": [ "Workspace" ], "summary": "Create Workspace", "description": "Creates a new workspace.\n\nA new API key scoped to the created workspace is generated and returned as `api_key`. Use it in the `x-api-key` header for requests against that workspace.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "createWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Workspace display name.", "example": "My New Workspace" } } } } } }, "responses": { "201": { "description": "Workspace created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "id": "ws_new123", "name": "My New Workspace", "api_key": "YOUR_NEW_WORKSPACE_API_KEY" }, "message": "Workspace created successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "put": { "tags": [ "Workspace" ], "summary": "Update Workspace", "description": "Renames the current workspace.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "updateWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New workspace name.", "example": "Updated Workspace Name" } } } } } }, "responses": { "200": { "description": "Workspace updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/workspace/invite": { "post": { "tags": [ "Workspace" ], "summary": "Invite User to Workspace", "description": "Sends an email invitation to join the workspace with the specified role.\n\n**Assignable roles:** `ADMIN`, `EDITOR`, `VIEWER`\n\nReturns `409` if the user is already a workspace member.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "inviteUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email", "description": "Invitee's email address.", "example": "teammate@company.com" }, "role": { "type": "string", "enum": [ "ADMIN", "EDITOR", "VIEWER" ], "description": "Role to assign.", "example": "EDITOR" } } } } } }, "responses": { "201": { "description": "Invitation sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Invitation sent to teammate@company.com" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "409": { "$ref": "#/components/responses/409" } } } }, "/wallet": { "get": { "tags": [ "Wallet" ], "summary": "Get Wallet Balance", "description": "Returns the current wallet balance and auto top-up configuration.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getWalletBalance", "responses": { "200": { "description": "Wallet details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Wallet" } } }, "example": { "success": true, "data": { "balance": 125.5, "currency": "USD", "auto_topup": { "enabled": true, "threshold": 10, "topup_amount": 50 } } } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/wallet/auto-topup": { "put": { "tags": [ "Wallet" ], "summary": "Configure Auto Top-up", "description": "Enables or disables automatic wallet recharging.\n\nWhen enabled, the wallet is topped up by `topup_amount` whenever the balance drops below `threshold`.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "configureAutoTopup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "`true` to enable, `false` to disable." }, "threshold": { "type": "number", "description": "Balance threshold to trigger top-up. Required when `enabled` is `true`.", "example": 10 }, "topup_amount": { "type": "number", "description": "Amount to add per top-up. Required when `enabled` is `true`.", "example": 50 } } }, "examples": { "enable": { "summary": "Enable auto top-up", "description": "Recharge $50 when balance falls below $10.", "value": { "enabled": true, "threshold": 10, "topup_amount": 50 } }, "disable": { "summary": "Disable auto top-up", "value": { "enabled": false } } } } } }, "responses": { "200": { "description": "Auto top-up settings updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/wallet/topup": { "post": { "tags": [ "Wallet" ], "summary": "Top-up Wallet", "description": "Adds credits to the workspace wallet.\n\n- If a saved payment method exists (auto-topup card on file), the charge is processed immediately and credits are added.\n- Otherwise, a Stripe Checkout session is created and a `checkout_url` is returned. Credits are added automatically via webhook after payment.\n\n> **Note:** After payment, check `GET /wallet` for the updated balance. No polling needed.\n\n**Amount:** $1–$10,000 USD\n\n**Rate limit:** 1 req/10s burst, 20 req/min sustained (workspace-scoped)", "operationId": "topupWallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Amount in USD to add (5–10000).", "example": 50, "minimum": 5, "maximum": 10000 } } } } } }, "responses": { "200": { "description": "Top-up completed immediately via saved card (auto-topup).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "status": "paid", "amount": 50 }, "message": "Top-up completed via auto-topup" } } } }, "201": { "description": "Checkout session created. User must complete payment at the returned URL. Credits are added automatically via webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "checkout_url": "https://checkout.stripe.com/...", "payment_id": "01ABC..." }, "message": "Checkout session created. Complete payment at the checkout URL. Credits will be added automatically via webhook." } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/available": { "get": { "tags": [ "Domain" ], "summary": "Check Domain Availability", "description": "Checks whether a domain is available for purchase and returns pricing information along with recommended alternatives.\n\n**Validation:**\n- `domain` is required and must be non-empty\n- Must not be a subdomain (e.g., `sub.example.com` is rejected)\n- Must not include protocol (`http://`, `https://`), `www.` prefix, or path\n- Must include a valid TLD (e.g., `example.com`)\n- Allowed TLDs: `com`, `net`, `org`, `biz`, `live`, `info` (configurable via `TLD` env variable)\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained (global domain rate limit)", "operationId": "checkDomainAvailability", "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Domain to check (e.g., `example.com`).", "example": "example.com" }, { "$ref": "#/components/parameters/page" }, { "name": "prefix", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated prefixes for suggestions (e.g., `get,try`).", "example": "get,try" }, { "name": "suffix", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated suffixes for suggestions (e.g., `hub,app`).", "example": "hub,app" }, { "name": "tld", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated TLDs to filter (e.g., `com,net,org`). Allowed: `com`, `net`, `org`, `biz`, `live`, `info`.", "example": "com,net,org" } ], "responses": { "200": { "description": "Domain availability and recommendations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "current_domain": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "available": { "type": "boolean", "example": true }, "pricing": { "type": "object", "properties": { "tld": { "type": "string", "example": "com" }, "price": { "type": "number", "example": 12.99 }, "currency": { "type": "string", "example": "USD" }, "duration": { "type": "integer", "example": 1 }, "duration_type": { "type": "string", "example": "YEAR" } } } } }, "recommended_domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "boolean" }, "pricing": { "type": "object", "properties": { "tld": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string" }, "duration": { "type": "integer" }, "duration_type": { "type": "string" } } } } } } } }, "message": { "type": "string", "example": "Domain availability checked successfully" } } }, "example": { "success": true, "data": { "current_domain": { "domain": "example.com", "available": true, "pricing": { "tld": "com", "price": 12.99, "currency": "USD", "duration": 1, "duration_type": "YEAR" } }, "recommended_domains": [ { "domain": "example.net", "available": true, "pricing": { "tld": "net", "price": 11.99, "currency": "USD", "duration": 1, "duration_type": "YEAR" } } ] }, "message": "Domain availability checked successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/{domainId}": { "get": { "tags": [ "Domain" ], "summary": "Get Domain by ID", "description": "Returns details for a specific domain.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getDomainById", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID.", "example": "dom_x1y2z3" } ], "responses": { "200": { "description": "Domain details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Domain" }, "message": { "type": "string", "example": "Domain fetched successfully" } } }, "example": { "success": true, "data": { "domain_id": "01DEF...", "domain": "example.com", "status": "ACTIVE", "created_at": "2026-04-27T10:00:00.000Z", "expires_at": "2027-04-27T10:00:00.000Z", "import": false, "order_id": "01ABC...", "mailbox_count": 3, "domain_forwarding": false, "domain_forwarding_url": "", "dmarc_email": "", "dmarc": true, "forwarding": false, "spf": true, "dkim": true, "mx_records": true, "active": true, "workspace_type": "GOOGLE", "cf_app_id": null, "prewarmed": false, "associate_with_google": true, "associate_with_microsoft": false, "blacklisted": false }, "message": "Domain fetched successfully" } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/domain/ns-records": { "get": { "tags": [ "Domain" ], "summary": "Fetch Nameservers", "description": "Returns the Icemail nameservers (NS records) that your domains should point to at your registrar.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "fetchNameservers", "responses": { "200": { "description": "Nameserver records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/{domainId}/dns-records": { "get": { "tags": [ "Domain" ], "summary": "Get DNS Records", "description": "Returns all DNS records for a domain.\n\n**Rate limit:** 5 req/s burst, 20 req/min sustained", "operationId": "getDnsRecords", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID." } ], "responses": { "200": { "description": "DNS record list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } } } }, "example": { "success": true, "data": [ { "id": "rec_001", "type": "A", "name": "@", "content": "1.2.3.4" }, { "id": "rec_002", "type": "MX", "name": "@", "content": "mail.example.com" }, { "id": "rec_003", "type": "TXT", "name": "@", "content": "v=spf1 include:example.com ~all" } ] } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "post": { "tags": [ "Domain" ], "summary": "Create DNS Records", "description": "Creates one or more DNS records for a domain.\n\n**Supported types:** `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`, `PTR`, `HTTPS`, `SVCB`, `TLSA`, `CAA`\n\nUse `@` as the `name` to target the root domain.\n\n**Rate limit:** 5 req/s burst, 20 req/min sustained", "operationId": "createDnsRecords", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "description": "One or more DNS records to create.", "items": { "type": "object", "required": [ "type", "name", "content" ], "properties": { "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "PTR", "HTTPS", "SVCB", "TLSA", "CAA" ] }, "name": { "type": "string", "description": "Record name. `@` for root, or a subdomain (e.g. `www`, `mail`).", "example": "@" }, "content": { "type": "string", "description": "Record value.", "example": "1.2.3.4" } } } } } }, "examples": { "basic_setup": { "summary": "Standard setup — A + MX + SPF", "value": { "records": [ { "type": "A", "name": "@", "content": "1.2.3.4" }, { "type": "MX", "name": "@", "content": "mail.example.com" }, { "type": "TXT", "name": "@", "content": "v=spf1 include:example.com ~all" } ] } }, "subdomain": { "summary": "Subdomain — point blog to a server", "value": { "records": [ { "type": "A", "name": "blog", "content": "5.6.7.8" } ] } } } } } }, "responses": { "201": { "description": "Records created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "put": { "tags": [ "Domain" ], "summary": "Update DNS Records", "description": "Updates existing DNS records. Each record in the array **must include its `id`**.\n\nUse `GET /domain/{domainId}/dns-records` to retrieve record IDs.\n\n**Rate limit:** 5 req/s burst, 20 req/min sustained", "operationId": "updateDnsRecords", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "description": "Records to update. Each must include the existing `id`.", "items": { "type": "object", "required": [ "id", "type", "name", "content" ], "properties": { "id": { "type": "string", "description": "Existing record ID.", "example": "rec_001" }, "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "PTR", "HTTPS", "SVCB", "TLSA", "CAA" ] }, "name": { "type": "string", "example": "@" }, "content": { "type": "string", "example": "5.6.7.8" } } } } } }, "example": { "records": [ { "id": "rec_001", "type": "A", "name": "@", "content": "5.6.7.8" } ] } } } }, "responses": { "200": { "description": "Records updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/domain/{domainId}/forwarding": { "put": { "tags": [ "Domain" ], "summary": "Update Domain Forwarding", "description": "Sets a forwarding URL for a domain. Visitors to this domain will be redirected to the specified URL.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "updateDomainForwarding", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "forwarding_url" ], "properties": { "forwarding_url": { "type": "string", "format": "uri", "description": "Destination URL (must include protocol).", "example": "https://example.com" }, "mask": { "type": "boolean", "default": true, "description": "Forwarding method for non-Cloudflare domains. `true` (default) uses domain masking; `false` uses basic 301 redirect. Ignored for Cloudflare-connected domains." } } } } } }, "responses": { "200": { "description": "Forwarding configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/domain/{domainId}/dmarc": { "put": { "tags": [ "Domain" ], "summary": "Update DMARC Record", "description": "Configures DMARC for a domain by setting the email that receives aggregate reports.\n\nDMARC (Domain-based Message Authentication, Reporting & Conformance) helps prevent email spoofing.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "updateDmarcRecord", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dmarc_email" ], "properties": { "dmarc_email": { "type": "string", "format": "email", "description": "Email to receive DMARC reports.", "example": "dmarc-reports@example.com" } } } } } }, "responses": { "200": { "description": "DMARC configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/domain/forwarding": { "put": { "tags": [ "Domain" ], "summary": "Bulk Assign Forwarding", "description": "Applies the same forwarding URL to multiple domains in a single request.\n\n**Rate limit:** 1 req/s burst, 10 req/min sustained", "operationId": "bulkAssignForwarding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids", "forwarding_url" ], "properties": { "domain_ids": { "type": "array", "description": "Domain IDs to apply forwarding to.", "items": { "type": "string", "format": "uuid" }, "example": [ "dom_abc123", "dom_def456" ] }, "forwarding_url": { "type": "string", "format": "uri", "description": "Destination URL for all listed domains.", "example": "https://example.com" }, "mask": { "type": "boolean", "default": true, "description": "Forwarding method for non-Cloudflare domains. `true` (default) uses domain masking; `false` uses basic 301 redirect. Ignored for Cloudflare-connected domains." } } } } } }, "responses": { "200": { "description": "Forwarding applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "delete": { "tags": [ "Domain" ], "summary": "Bulk Remove Forwarding", "description": "Removes forwarding configuration from multiple domains.\n\n**Rate limit:** 1 req/s burst, 10 req/min sustained", "operationId": "bulkRemoveForwarding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids" ], "properties": { "domain_ids": { "type": "array", "description": "Domain IDs to remove forwarding from.", "items": { "type": "string", "format": "uuid" }, "example": [ "dom_abc123", "dom_def456" ] } } } } } }, "responses": { "200": { "description": "Forwarding removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/dmarc": { "put": { "tags": [ "Domain" ], "summary": "Bulk Assign DMARC", "description": "Applies the same DMARC reporting email to multiple domains.\n\n**Rate limit:** 1 req/s burst, 10 req/min sustained", "operationId": "bulkAssignDmarc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids", "dmarc_email" ], "properties": { "domain_ids": { "type": "array", "description": "Domain IDs to configure.", "items": { "type": "string", "format": "uuid" }, "example": [ "dom_abc123", "dom_def456" ] }, "dmarc_email": { "type": "string", "format": "email", "description": "DMARC report recipient for all listed domains.", "example": "dmarc-reports@example.com" } } } } } }, "responses": { "200": { "description": "DMARC applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "delete": { "tags": [ "Domain" ], "summary": "Bulk Remove DMARC", "description": "Removes DMARC configuration from multiple domains. DMARC reports will no longer be sent for these domains.\n\n**Rate limit:** 1 req/s burst, 10 req/min sustained", "operationId": "bulkRemoveDmarc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids" ], "properties": { "domain_ids": { "type": "array", "description": "Domain IDs to remove DMARC from.", "items": { "type": "string", "format": "uuid" }, "example": [ "dom_abc123", "dom_def456" ] } } } } } }, "responses": { "200": { "description": "DMARC removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/add-google-client-id": { "post": { "tags": [ "Domain" ], "summary": "Add Google OAuth Client ID", "description": "Pushes a Google OAuth `client_id` to the master inbox of each given domain (queues a `CLIENTID` export job per domain).\n\nEach domain has a **15-minute cooldown** — a domain processed within the last 15 minutes is returned under `skipped` instead of being re-queued.\n\nThe job runs asynchronously — subscribe to the `order.client_id.completed` / `order.client_id.failed` webhooks for the per-mailbox result.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "addGoogleClientId", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "domain_ids" ], "properties": { "client_id": { "type": "string", "description": "Google OAuth client ID to push.", "example": "1234567890-abcdef.apps.googleusercontent.com" }, "domain_ids": { "type": "array", "description": "IDs of the domains to push the client ID to.", "items": { "type": "string" }, "example": [ "01DEF...", "01GHI..." ] } } }, "example": { "client_id": "1234567890-abcdef.apps.googleusercontent.com", "domain_ids": [ "01DEF...", "01GHI..." ] } } } }, "responses": { "200": { "description": "Client ID push processed per domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "CLIENTID push completed", "data": { "client_id": "1234567890-abcdef.apps.googleusercontent.com", "queued": [ { "domain": "example.com", "mailbox": "admin@example.com" } ], "skipped": [ { "domain": "recent.com", "mailbox": "admin@recent.com", "reason": "cooldown: domain processed recently, retry in 12 min" } ], "failed": [], "not_found_domains": [ "01GHI..." ] } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/mailboxes": { "delete": { "tags": [ "Domain" ], "summary": "Delete Mailboxes by Domain", "description": "**Stage 1 of the domain wind-down flow.** Use when you want to wind down all mailboxes on one or more domains — either right now, or at the end of the current billing cycle to avoid forfeiting paid-for runway.\n\n**What it does:** for each domain in `domain_ids`, deletes every mailbox on that domain. The Domains row, DNS zone, and DNS records are **not** touched — only the mailboxes go.\n\n**Modes:**\n- `\"immediate\"` (default) — Mailboxes are deleted permanently. There is no waiting period, recovery option, or undo action. Once a mailbox is deleted, all associated data is removed and cannot be restored. Only proceed if you are certain that you want to permanently delete the mailbox.\n- `\"scheduled\"` — sets a `scheduled_deletion_at` on each mailbox equal to the **earliest** `next_billing_date` across the domain's active mailboxes. Mailboxes keep working normally until that date, then auto-delete via a trigger. Cancel by uncancelling the underlying subscription before the date arrives.\n\n> **Notes:**\n> - `skipped: true` on a `per_domain` entry means the domain had no active mailboxes — nothing to do.\n> - `error: \"\"` on a `per_domain` entry means that single domain failed (e.g. no billing data for `scheduled` mode); the rest of the batch still proceeds.\n> - For `scheduled` mode the resolved date must be in the future. Domains whose `next_billing_date` is already past must use `mode: \"immediate\"`.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "deleteMailboxesByDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids" ], "properties": { "domain_ids": { "type": "array", "description": "Non-empty array of domain IDs to wind down.", "items": { "type": "string" }, "example": [ "01DEF...", "01GHI..." ] }, "mode": { "type": "string", "enum": [ "immediate", "scheduled" ], "default": "immediate", "description": "`immediate` (default) soft-deletes now; `scheduled` deletes at the earliest `next_billing_date` (end-of-cycle)." } } }, "examples": { "immediate": { "summary": "Immediate deletion", "value": { "domain_ids": [ "01DEF...", "01GHI..." ], "mode": "immediate" } }, "scheduled": { "summary": "End-of-cycle (scheduled) deletion", "value": { "domain_ids": [ "01DEF..." ], "mode": "scheduled" } } } } } }, "responses": { "200": { "description": "Mailboxes deleted (or scheduled) per domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Mailboxes deleted successfully", "data": { "mode": "immediate", "per_domain": [ { "domain_id": "01DEF...", "mode": "immediate", "mailbox_ids": [ "01MBX1...", "01MBX2..." ] }, { "domain_id": "01GHI...", "mode": "immediate", "mailbox_ids": [], "skipped": true } ], "summary": { "domains_requested": 2, "domains_processed": 1, "domains_skipped": 1, "domains_failed": 0, "mailboxes_affected": 2 } } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain/clear-dns": { "delete": { "tags": [ "Domain" ], "summary": "Clear DNS Records", "description": "**Stage 2 of the domain wind-down flow.** Use when the domain has no active mailboxes anymore and you want to **reuse it for a fresh mailbox batch**. This is the right call after Delete Mailboxes when you don't want to give up the domain itself — just remove the stale MX / SPF / DKIM / DMARC / forwarding records tied to the old mailboxes.\n\n**What it does:** queues a bulk action that, per domain, wipes every zone record except NS/SOA, resets the domain row's DNS flags (`dkim`, `spf`, `dmarc`, `mx_records`, `forwarding`, `domain_forwarding`) to false, and nulls the forwarding text fields. The DNS **zone itself stays** (so the domain is still ready to host records again) and the Domains row stays in your listing.\n\n**Why not just call Delete Domain?** Delete Domain destroys the zone and removes the domain from your listing — if you intend to put new mailboxes on the same domain later, you'd have to re-import / re-purchase. Clear DNS keeps the zone alive so you can immediately allocate new mailboxes to it.\n\n**Per-domain preconditions enforced by the worker (silently skipped if not met):**\n- Domain must have **zero active mailboxes** — otherwise silently skipped (call Delete Mailboxes first).\n- All-or-nothing on DNS deletion: if any record delete fails for a domain, that domain's flag reset is skipped — operator retries.\n\n**Async:** responds **202** immediately with a `correlation_id`. Processing typically completes in 10–15 minutes.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "clearDomainDns", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids" ], "properties": { "domain_ids": { "type": "array", "description": "IDs of the domains whose DNS records should be cleared.", "items": { "type": "string" }, "example": [ "01DEF...", "01GHI..." ] } } } } } }, "responses": { "202": { "description": "Clear DNS action queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Clear DNS action queued — propagation typically completes in 10–15 minutes." }, "data": { "type": "object", "properties": { "action": { "type": "string", "example": "clear_dns_records" }, "estimated_domains": { "type": "integer", "example": 2 }, "correlation_id": { "type": "string", "example": "01HMR..." } } } } }, "example": { "success": true, "message": "Clear DNS action queued — propagation typically completes in 10–15 minutes.", "data": { "action": "clear_dns_records", "estimated_domains": 2, "correlation_id": "01HMR..." } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/domain": { "delete": { "tags": [ "Domain" ], "summary": "Delete Domains", "description": "**Stage 3 of the domain wind-down flow** — the terminal step. Use when you're done with the domain entirely and want it gone from your listing. After this the domain is no longer queryable through the public API and you can't reuse it without re-importing or re-purchasing.\n\n**What it does:** queues a bulk action that, per domain, **deletes** the Domains row and any leftover inactive mailbox rows. For ClouDNS-hosted domains the zone is also deleted from ClouDNS. For Cloudflare-managed domains (connected via your own Cloudflare API key) the zone is left intact — only the platform's DB association is removed.\n\n**Per-domain preconditions enforced by the worker (silently skipped if not met):**\n- **Purchased domains** (`import=false`) are silently skipped. The registrar lifecycle for purchased domains is separate; this endpoint only handles connected domains you brought to the platform.\n- Domains with active mailboxes are silently skipped. Call **Delete Mailboxes by Domain** first.\n\n**Async:** responds **202** immediately with a `correlation_id`. Processing typically completes in 10–15 minutes.\n\n> **Warning:** This is destructive. The Domains row and all linked inactive mailboxes are permanently deleted and are no longer queryable through the public API.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "deleteDomains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids" ], "properties": { "domain_ids": { "type": "array", "description": "IDs of the domains to delete.", "items": { "type": "string" }, "example": [ "01DEF...", "01GHI..." ] } } } } } }, "responses": { "202": { "description": "Delete Domain action queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Delete Domain action queued — propagation typically completes in 10–15 minutes." }, "data": { "type": "object", "properties": { "action": { "type": "string", "example": "delete_domain" }, "estimated_domains": { "type": "integer", "example": 2 }, "correlation_id": { "type": "string", "example": "01HMR..." } } } } }, "example": { "success": true, "message": "Delete Domain action queued — propagation typically completes in 10–15 minutes.", "data": { "action": "delete_domain", "estimated_domains": 2, "correlation_id": "01HMR..." } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "get": { "tags": [ "Domain" ], "summary": "List Domains", "description": "Returns all domains in the workspace with pagination and optional search.\n\nThe `search` parameter performs a case-insensitive partial match on the domain name.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "listDomains", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter by domain name (case-insensitive partial match).", "example": "example" } ], "responses": { "200": { "description": "Paginated domain list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "total_count": { "type": "integer", "description": "Total domains matching the filter, across all pages.", "example": 1 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 10 } } }, "message": { "type": "string", "example": "Domains fetched successfully" } } }, "example": { "success": true, "data": { "domains": [ { "domain_id": "01DEF...", "domain": "example.com", "status": "ACTIVE", "created_at": "2026-04-27T10:00:00.000Z", "expires_at": "2027-04-27T10:00:00.000Z", "import": false, "order_id": "01ABC...", "mailbox_count": 3, "domain_forwarding": false, "domain_forwarding_url": "", "dmarc_email": "", "dmarc": true, "forwarding": false, "spf": true, "dkim": true, "mx_records": true, "active": true, "workspace_type": "GOOGLE", "cf_app_id": null, "prewarmed": false, "associate_with_google": true, "associate_with_microsoft": false, "blacklisted": false } ], "total_count": 1, "page": 1, "limit": 10 }, "message": "Domains fetched successfully" } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/order": { "post": { "tags": [ "Order" ], "summary": "Create Order", "description": "Purchases new domains and provisions mailboxes, or imports existing domains and creates mailboxes — all in a single request.\n\n- **`import: false` (default):** Domains are purchased. Credits are charged for both domains and mailboxes. DNS is managed by Icemail.\n- **`import: true`:** Domains are imported, so no domain purchase charge applies. Credits are charged for mailboxes only, and DNS is managed by Icemail.\n - **Cloudflare (optional):** add a top-level `cloudflare` object (`email` + a scoped Cloudflare API `api_key`) to host the imported domains' DNS on your own Cloudflare zone instead of Icemail DNS; the same `email` reuses one stored connection. **The `api_key` must be a Cloudflare API token with these permissions: `Zone.Zone` (Edit), `Zone.DNS` (Edit), and Zone Resources → All zones.** Omit it for a normal import — don't send `null` / `{}` / a partial object (that returns 400).\n\n> **Note:** Before importing a domain to Icemail, point your domain's nameservers at your registrar to `pns71.cloudns.net`, `pns72.cloudns.com`, `pns73.cloudns.net`, `pns74.cloudns.uk`.\n>\n> Skip this if you use your own Cloudflare account — the domain keeps its Cloudflare nameservers.\n\n> **Note:** Avoid placing mailbox orders for the same domain through individual requests. Instead, submit all mailboxes for a domain in a single request to ensure proper processing and avoid workflow inconsistencies.\n\n### Bulk Providers (CUSTOM / AZURE)\n\n`CUSTOM` (SMTP) and `AZURE` are **bundle** providers: they are sold as fixed-capacity plans rather than per-mailbox. You do **not** pick a plan — send the same `domain_name` + `mailboxes` shape as Google/Microsoft and the API **auto-selects and purchases the cheapest plan(s)** that fit your order, then allocates the mailboxes into them. Re-ordering for the same provider reuses any remaining capacity before buying more.\n\n- **CUSTOM** — up to **15 mailboxes per domain**. Plans cover STARTER (2 domains), GROWTH (4), PRO (6); the API picks the cheapest cover automatically.\n- **AZURE** — each domain must have **exactly 100 mailboxes** (one BASIC plan = one domain). Provisioning is **asynchronous**: the order returns immediately with the mailboxes in `PENDING` status, and they become `ACTIVE` later (subscribe to the `order.mailbox.active` webhook or poll `GET /api/v1/mailbox`).\n\n> The `import: true` flag works for bulk providers too (import an existing domain, pay for the bundle only). The AZURE 100-per-domain rule and the CUSTOM 15-per-domain limit still apply.\n\n**Constraints:**\n- `data` must contain 1–100 entries with no duplicate `domain_name`. Each request can include up to 100 domains (i.e., `data.length` ≤ 100).\n- Each `mailboxes[].username` must end with `@{domain_name}`.\n- `first_name`, `last_name`, and `username` are mandatory fields for each mailbox.\n- `password` is **optional**. Omit it, or send `null` / `\"\"`, and system generates a secure password for the mailbox. If you send one, it must:\n - be 8–24 characters long\n - start with a letter (`A-Z` / `a-z`)\n - contain at least one uppercase letter, one lowercase letter, one number, and one symbol\n - use only letters, numbers, and the symbols `! @ # $ % & ?` (no spaces or other symbols)\n\n An invalid password returns `400` with the rules in the error message. Example of a valid password: `SecurePass1!`.\n- `domain_forwarding`, `email_forwarding`, and `profile_url` are optional.\n- **Per-provider mailbox counts:** **CUSTOM** ≤ 15 mailboxes per domain; **AZURE** exactly 100 mailboxes per domain. (GOOGLE / MICROSOFT have no fixed per-domain cap.)\n\n**Rate limit:** 1 req/5s burst, 12 req/min sustained (workspace-scoped)", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "import": { "type": "boolean", "description": "`true` to import existing domains (no domain charge). `false` (default) to purchase new domains.", "default": false, "example": false }, "cloudflare": { "type": "object", "description": "Optional, import-only. Hosts the imported domains' DNS on your own Cloudflare zone instead of Icemail DNS. `email` + a scoped API `api_key`, reused per `email`. Omit for a Icemail DNS import (`null` / `{}` / partial → 400).", "required": [ "email", "api_key" ], "properties": { "email": { "type": "string", "format": "email", "description": "Your Cloudflare account email.", "example": "you@example.com" }, "api_key": { "type": "string", "description": "A Cloudflare API token. **Required permissions:** `Zone.Zone` (Edit), `Zone.DNS` (Edit), and Zone Resources → All zones. Stored as sent; not re-validated on later orders.", "example": "cf_scoped_api_token_xxx" } } }, "data": { "type": "array", "description": "Array of 1–100 domain entries. No duplicate `domain_name` allowed.", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "domain_name", "mailbox_type", "mailboxes" ], "properties": { "domain_name": { "type": "string", "description": "Domain to purchase or import.", "example": "example.com" }, "mailbox_type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT", "CUSTOM", "AZURE" ], "description": "Email provider for the mailboxes. `CUSTOM` (SMTP) and `AZURE` are bundle providers — see **Bulk Providers** above.", "example": "GOOGLE" }, "domain_forwarding": { "type": "string", "format": "uri", "description": "Optional URL to forward the domain to.", "example": "https://mysite.com" }, "mailboxes": { "type": "array", "description": "Non-empty array of mailboxes to create for this domain. **CUSTOM:** ≤ 15 per domain. **AZURE:** exactly 100 per domain.", "minItems": 1, "items": { "type": "object", "required": [ "first_name", "last_name", "username" ], "properties": { "first_name": { "type": "string", "description": "First name.", "example": "John" }, "last_name": { "type": "string", "description": "Last name.", "example": "Doe" }, "username": { "type": "string", "description": "Full email address. Must end with `@{domain_name}`.", "example": "john@example.com" }, "password": { "type": "string", "nullable": true, "description": "Optional mailbox password. Omit it (or send `null` / empty string) to have Icemail auto-generate one. If provided: 8–24 characters, must start with a letter, and must contain at least one uppercase letter, one lowercase letter, one number, and one symbol from `! @ # $ % & ?`. No spaces or other symbols are allowed. Invalid passwords return `400`.", "example": "SecurePass1!", "minLength": 8, "maxLength": 24, "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[!@#$%&?])[A-Za-z][A-Za-z\\d!@#$%&?]{7,23}$" }, "email_forwarding": { "type": "string", "format": "email", "description": "Optional recovery/forwarding email.", "example": "john.fwd@gmail.com" }, "profile_url": { "type": "string", "format": "uri", "description": "Optional profile image URL.", "example": "https://pic.com/avatar.jpg" } } } } } } } } }, "examples": { "buy_domains": { "summary": "Purchase new domains with mailboxes (Domain and DNS managed by Icemail)", "value": { "import": false, "data": [ { "domain_name": "example.com", "mailbox_type": "GOOGLE", "domain_forwarding": "https://mysite.com", "mailboxes": [ { "first_name": "John", "last_name": "Doe", "username": "john@example.com", "password": "SecurePass1!", "email_forwarding": "john.fwd@gmail.com", "profile_url": "https://pic.com/avatar.jpg" } ] }, { "domain_name": "another.net", "mailbox_type": "MICROSOFT", "mailboxes": [ { "first_name": "Jane", "last_name": "Smith", "username": "jane@another.net", "password": "SecurePass2!" } ] } ] } }, "import_domains": { "summary": "Import existing domains (you own them) — DNS managed by Icemail", "value": { "import": true, "data": [ { "domain_name": "myexisting.com", "mailbox_type": "GOOGLE", "mailboxes": [ { "first_name": "Alice", "last_name": "Brown", "username": "alice@myexisting.com", "password": "SecurePass3!" } ] } ] } }, "cloudflare_import": { "summary": "Import existing domains (you own them) — DNS managed by your Cloudflare account", "value": { "import": true, "cloudflare": { "email": "you@example.com", "api_key": "cf_scoped_api_token_xxx" }, "data": [ { "domain_name": "myexisting.com", "mailbox_type": "GOOGLE", "mailboxes": [ { "first_name": "Alice", "last_name": "Brown", "username": "alice@myexisting.com", "password": "SecurePass3!" } ] } ] } }, "custom_bulk": { "summary": "Bulk provider — CUSTOM (SMTP), ≤ 15 mailboxes per domain", "value": { "data": [ { "domain_name": "example.com", "mailbox_type": "CUSTOM", "mailboxes": [ { "first_name": "John", "last_name": "Doe", "username": "john@example.com", "password": "SecurePass1!", "email_forwarding": "john.fwd@gmail.com" } ] } ] } }, "azure_bulk": { "summary": "Bulk provider — AZURE, exactly 100 mailboxes per domain (async PENDING → ACTIVE)", "value": { "data": [ { "domain_name": "example.com", "mailbox_type": "AZURE", "mailboxes": [ { "first_name": "User", "last_name": "One", "username": "user1@example.com", "password": "SecurePass1!" } ] } ] } } } } } }, "responses": { "201": { "description": "Order created. Returns one entry per domain in the same order as the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": [ { "order_id": "01ABC...", "import": false, "domain_id": "01DEF...", "domain_name": "example.com", "domain_forwarding": "https://mysite.com", "mailbox_type": "GOOGLE", "mailboxes": [ { "mailbox_id": "01GHI...", "first_name": "John", "last_name": "Doe", "username": "john@example.com", "password": "SecurePass1!", "email_forwarding": "john.fwd@gmail.com", "profile_url": "https://pic.com/avatar.jpg" } ] } ], "message": "Order created successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/mailbox": { "get": { "tags": [ "Mailbox" ], "summary": "List Mailboxes", "description": "Returns all mailboxes in the workspace with pagination, search, and provider filtering.\n\nThe `search` parameter matches against `first_name`, `last_name`, and `username`.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "listMailboxes", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter by name or username.", "example": "john" }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT", "CUSTOM" ] }, "description": "Filter by provider." } ], "responses": { "200": { "description": "Paginated mailbox list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "mailboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "total_count": { "type": "integer", "description": "Total mailboxes matching the filter, across all pages.", "example": 1 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 10 } } }, "message": { "type": "string", "example": "Mailboxes fetched successfully" } } }, "example": { "success": true, "data": { "mailboxes": [ { "id": "01GHI...", "first_name": "John", "last_name": "Doe", "username": "john@example.com", "recovery_email": "john.recovery@gmail.com", "forward_email": "john.fwd@gmail.com", "type": "GOOGLE", "status": "ACTIVE", "active": true, "master_inbox": false, "created_at": "2026-04-27T10:00:00.000Z", "modified_at": "2026-04-27T10:00:00.000Z", "password": "Plaintext", "domains": { "domain_id": "01DEF...", "domain": "example.com" }, "next_billing_date": "2026-05-27T10:00:00.000Z", "cost": "4.99", "billing_cycle": "MONTHLY" } ], "total_count": 1, "page": 1, "limit": 10 }, "message": "Mailboxes fetched successfully" } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/mailbox/price": { "get": { "tags": [ "Mailbox" ], "summary": "Get Mailbox Prices", "description": "Returns direct (per-mailbox) pricing for GOOGLE and MICROSOFT, plus bundle-wise plan pricing for CUSTOM and AZURE — all in one call. All prices are in USD.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getMailboxPrices", "responses": { "200": { "description": "Resolved mailbox pricing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MailboxPricing" }, "message": { "type": "string", "example": "Mailbox prices fetched successfully" } } }, "example": { "success": true, "data": { "direct": { "GOOGLE": 5.0, "MICROSOFT": 4.0 }, "bundles": { "CUSTOM": { "STARTER": { "mailbox_limit": 30, "domain_limit": 2, "mailbox_per_domain": 15, "price": 49 }, "GROWTH": { "mailbox_limit": 60, "domain_limit": 4, "mailbox_per_domain": 15, "price": 99 }, "PRO": { "mailbox_limit": 90, "domain_limit": 6, "mailbox_per_domain": 15, "price": 149 } }, "AZURE": { "BASIC": { "mailbox_limit": 100, "domain_limit": 1, "mailbox_per_domain": 100, "price": 30 } } } }, "message": "Mailbox prices fetched successfully" } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/mailbox/{mailboxId}": { "get": { "tags": [ "Mailbox" ], "summary": "Get Mailbox by ID", "description": "Returns details for a specific mailbox.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getMailboxById", "parameters": [ { "name": "mailboxId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mailbox ID.", "example": "mbx_p1q2r3" } ], "responses": { "200": { "description": "Mailbox details. `password` is returned as decrypted plaintext (or `null` if not set) — treat the response as sensitive. Billing fields are `null` when no purchase record exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Mailbox" }, "message": { "type": "string", "example": "Mailbox fetched successfully" } } }, "example": { "success": true, "data": { "id": "01GHI...", "first_name": "John", "last_name": "Doe", "username": "john@example.com", "recovery_email": "john.recovery@gmail.com", "forward_email": "john.fwd@gmail.com", "type": "GOOGLE", "status": "ACTIVE", "active": true, "master_inbox": false, "created_at": "2026-04-27T10:00:00.000Z", "modified_at": "2026-04-27T10:00:00.000Z", "password": "Plaintext", "domains": { "domain_id": "01DEF...", "domain": "example.com" }, "next_billing_date": "2026-05-27T10:00:00.000Z", "cost": "4.99", "billing_cycle": "MONTHLY" }, "message": "Mailbox fetched successfully" } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "put": { "tags": [ "Mailbox" ], "summary": "Update Mailbox Details", "description": "Updates a mailbox's display name, username, or profile picture. At least one field must be provided.\n\nChanging `username` will change the email address (e.g. `john@example.com` becomes `jane@example.com`).\n\n**Profile picture:** pass a public `profile_url` (HTTPS, JPEG or PNG, max 10MB). The image is downloaded, validated, stored, and pushed to the mailbox provider; the previous profile picture is replaced. An invalid, oversized, non-image, or non-HTTPS URL returns `400`.\n\n**Rate limit:** 5 req/s burst, 20 req/min sustained", "operationId": "updateMailbox", "parameters": [ { "name": "mailboxId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mailbox ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one field is required.", "properties": { "first_name": { "type": "string", "description": "New first name.", "example": "John" }, "last_name": { "type": "string", "description": "New last name.", "example": "Doe" }, "username": { "type": "string", "description": "New username (local part of email).", "example": "johndoe" }, "profile_url": { "type": "string", "format": "uri", "description": "Public HTTPS URL of the new profile picture (JPEG or PNG, max 5MB). Downloaded and replaces the existing picture.", "example": "https://pic.com/avatar.jpg" } } }, "examples": { "update_name": { "summary": "Update display name", "value": { "first_name": "John", "last_name": "Doe" } }, "change_username": { "summary": "Change email username", "value": { "username": "john.doe" } }, "update_profile_picture": { "summary": "Update profile picture", "value": { "profile_url": "https://pic.com/avatar.jpg" } } } } } }, "responses": { "200": { "description": "Mailbox update queued. The update is made, so `status` is returned as `UPDATING`. `old_username` appears on an entry only when the username changed; `old_forward_email` likewise appears only when the forwarding email changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MailboxUpdateResult" }, "message": { "type": "string", "example": "Mailbox updated successfully" } } }, "example": { "success": true, "data": { "updated_mailboxes": [ { "id": "01GHI...", "first_name": "John", "last_name": "Doe", "username": "johndoe@example.com", "recovery_email": "john.recovery@gmail.com", "forward_email": "john.fwd@gmail.com", "type": "GOOGLE", "warmup_duration": 14, "created_at": "2026-04-27T10:00:00.000Z", "modified_at": "2026-04-27T10:05:00.000Z", "active": true, "status": "UPDATING", "domain_id": "01DEF...", "admin": false, "cycle_intervel": 0, "old_username": "john@example.com" } ], "failed_updates": [], "summary": { "total_requested": 1, "successful": 1, "failed": 0 } }, "message": "Mailbox updated successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/mailbox/domain/{domainId}": { "get": { "tags": [ "Mailbox" ], "summary": "Get Mailboxes by Domain", "description": "Returns all mailboxes belonging to a specific domain.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getMailboxesByDomain", "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Domain ID." }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/limit" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter mailboxes within this domain." } ], "responses": { "200": { "description": "Mailboxes for the domain. This endpoint returns a **reduced mailbox shape** that differs from `GET /mailbox` and `GET /mailbox/{id}`: it does not include `password`, the nested `domains` object, or the billing fields, and there is no `total_count`. It does add `warmup_duration` (warm-up period in days).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "mailboxes": { "type": "array", "items": { "$ref": "#/components/schemas/DomainMailbox" } }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 10 } } }, "message": { "type": "string", "example": "Mailboxes fetched successfully" } } }, "example": { "success": true, "data": { "mailboxes": [ { "id": "01GHI...", "first_name": "John", "last_name": "Doe", "username": "john@example.com", "recovery_email": "john.recovery@gmail.com", "forward_email": "john.fwd@gmail.com", "type": "GOOGLE", "warmup_duration": 14, "created_at": "2026-04-27T10:00:00.000Z", "modified_at": "2026-04-27T10:00:00.000Z", "active": true, "status": "ACTIVE", "domain_id": "01DEF...", "master_inbox": false } ], "page": 1, "limit": 10 }, "message": "Mailboxes fetched successfully" } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/mailbox/forwarding": { "put": { "tags": [ "Mailbox" ], "summary": "Bulk Update Mailbox Forwarding", "description": "Sets the same forwarding email for multiple mailboxes. Incoming mail to these mailboxes will be forwarded to the specified address.\n\n**Rate limit:** 5 req/s burst, 20 req/min sustained", "operationId": "bulkUpdateMailboxForwarding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mailbox_ids", "forward_email" ], "properties": { "mailbox_ids": { "type": "array", "description": "Mailbox IDs to configure.", "items": { "type": "string", "format": "uuid" }, "example": [ "mbx_abc123", "mbx_def456" ] }, "forward_email": { "type": "string", "format": "email", "description": "Email address to forward to.", "example": "team-inbox@company.com" } } } } } }, "responses": { "200": { "description": "Forwarding update queued. Returns one entry per mailbox in `mailbox_ids`, with the same `{ updated_mailboxes, failed_updates, summary }` shape as Update Mailbox Details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MailboxUpdateResult" }, "message": { "type": "string", "example": "Mailbox forwarding updated successfully" } } }, "example": { "success": true, "data": { "updated_mailboxes": [ { "id": "01GHI...", "first_name": "John", "last_name": "Doe", "username": "john@example.com", "recovery_email": "john.recovery@gmail.com", "forward_email": "forward@example.com", "type": "GOOGLE", "warmup_duration": 14, "created_at": "2026-04-27T10:00:00.000Z", "modified_at": "2026-04-27T10:05:00.000Z", "active": true, "status": "UPDATING", "domain_id": "01DEF...", "admin": false, "cycle_intervel": 0, "old_forward_email": "john.fwd@gmail.com" } ], "failed_updates": [], "summary": { "total_requested": 1, "successful": 1, "failed": 0 } }, "message": "Mailbox forwarding updated successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "delete": { "tags": [ "Mailbox" ], "summary": "Bulk Delete Mailbox Forwarding", "description": "Removes email forwarding for the given mailboxes at the provider and clears `forward_email`. Processed asynchronously (takes a few minutes to propagate).\n\n**CUSTOM mailboxes are skipped** — they have no provider forwarding rule. If every id is a CUSTOM mailbox (or none match the workspace), returns `400`.\n\n**Rate limit:** 5 req/s burst, 20 req/min sustained", "operationId": "bulkDeleteMailboxForwarding", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mailbox_ids" ], "properties": { "mailbox_ids": { "type": "array", "description": "Mailbox IDs to clear forwarding for.", "items": { "type": "string", "format": "uuid" }, "example": [ "mbx_abc123", "mbx_def456" ] } } } } } }, "responses": { "200": { "description": "Forwarding removal queued for the given mailboxes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Mailbox forwarding removal queued" } } }, "example": { "success": true, "message": "Mailbox forwarding removal queued" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/mailbox/{mailboxId}/auth": { "get": { "tags": [ "Mailbox" ], "summary": "Get Authenticator Code", "description": "Returns the current 2FA TOTP code for a mailbox.\n\n- If 2FA is configured: returns `{ token, remaining }` with the 6-digit code and seconds until expiry.\n- If 2FA is not configured: returns `null`.\n\nTOTP codes typically refresh every 30 seconds.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getMailboxAuthCode", "parameters": [ { "name": "mailboxId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mailbox ID." } ], "responses": { "200": { "description": "Authenticator code or `null`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AuthCode" } } }, "examples": { "with_2fa": { "summary": "2FA configured", "value": { "success": true, "data": { "token": "482913", "remaining": 22 } } }, "without_2fa": { "summary": "2FA not configured", "value": { "success": true, "data": null } } } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/mailbox/{mailboxId}/app-password": { "get": { "tags": [ "Mailbox" ], "summary": "Get Mailbox App Password", "description": "Returns the decrypted Google app password for a **GOOGLE** mailbox, or `null` when unset.\n\nNon-Google mailboxes return `400`; unknown ids return `404`.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getMailboxAppPassword", "parameters": [ { "name": "mailboxId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Mailbox ID (GOOGLE only)." } ], "responses": { "200": { "description": "App password or `null`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "app_password": { "type": "string", "nullable": true, "description": "Decrypted Google app password, or null if unset.", "example": "abcd efgh ijkl mnop" } } } } }, "examples": { "set": { "summary": "App password set", "value": { "success": true, "data": { "app_password": "abcd efgh ijkl mnop" } } }, "unset": { "summary": "App password not set", "value": { "success": true, "data": { "app_password": null } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/prewarm": { "get": { "tags": [ "Pre-Warm" ], "summary": "List Pre-Warm Domains", "description": "Returns all domains currently in the pre-warming phase with pagination and optional search.\n\nThe `search` parameter performs a case-insensitive partial match on the domain name.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "listPreWarmDomains", "parameters": [ { "$ref": "#/components/parameters/page" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Items per page (max 100)." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter by domain name (case-insensitive partial match).", "example": "example" } ], "responses": { "200": { "description": "Paginated list of pre-warm domains.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Pre-warm domain identifier.", "example": "pw-domain-1" }, "domain": { "type": "string", "description": "Domain name.", "example": "warmeddomain.com" }, "per_domain_price": { "type": "number", "description": "Price per domain.", "example": 5.5 }, "per_mailbox_price": { "type": "number", "description": "Price per mailbox.", "example": 2.5 }, "mailbox_count": { "type": "integer", "description": "Number of mailboxes on this domain.", "example": 3 }, "active": { "type": "boolean", "description": "Whether the domain is actively pre-warming.", "example": true }, "pre_warm_mailbox": { "type": "array", "description": "Mailboxes associated with this pre-warm domain.", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "Full email address.", "example": "john@warmeddomain.com" }, "first_name": { "type": "string", "description": "First name.", "example": "John" }, "last_name": { "type": "string", "description": "Last name.", "example": "Doe" }, "type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT" ], "description": "Email provider.", "example": "GOOGLE" }, "admin": { "type": "boolean", "description": "Whether this mailbox is an admin.", "example": true }, "master_inbox": { "type": "boolean", "description": "Whether this is the master inbox.", "example": true }, "per_mailbox_price": { "type": "number", "description": "Price for this mailbox.", "example": 2.5 } } } } } } } } }, "message": { "type": "string", "example": "Pre-warm domains fetched successfully" } } }, "examples": { "with_data": { "summary": "Domains found", "value": { "success": true, "data": { "domains": [ { "id": "pw-domain-1", "domain": "warmeddomain.com", "per_domain_price": 5.5, "per_mailbox_price": 2.5, "mailbox_count": 3, "active": true, "pre_warm_mailbox": [ { "username": "john@warmeddomain.com", "first_name": "John", "last_name": "Doe", "type": "GOOGLE", "admin": true, "master_inbox": true, "per_mailbox_price": 2.5 } ] } ] }, "message": "Pre-warm domains fetched successfully" } }, "no_data": { "summary": "No domains found", "value": { "success": true, "data": { "domains": [] }, "message": "No pre-warm domains found" } } } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/prewarm/buy": { "post": { "tags": [ "Pre-Warm" ], "summary": "Buy Pre-Warm Domains", "description": "Purchases one or more pre-warm domains. Credits are deducted for each domain and its associated mailboxes.\n\nReturns details of successful and failed purchases.\n\n> **Note:** On successful purchase, new domain IDs and mailbox IDs are generated and associated with your account. Use these IDs to manage the domains and mailboxes via the Domain and Mailbox endpoints.\n\n**Rate limit:** 1 req/5s burst, 12 req/min sustained (workspace-scoped)", "operationId": "buyPreWarmDomains", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain_ids" ], "properties": { "domain_ids": { "type": "array", "description": "Array of 1–50 pre-warm domain IDs to purchase.", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "example": [ "pw-domain-1", "pw-domain-2" ] } } } } } }, "responses": { "200": { "description": "Purchase completed. Some domains may have failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Order identifier.", "example": "01ABC..." }, "successful_domains": { "type": "array", "items": { "type": "object", "properties": { "domain_id": { "type": "string", "example": "01DEF..." }, "domain_name": { "type": "string", "example": "warmeddomain.com" }, "domain_price": { "type": "number", "example": 5.5 }, "mailbox_count": { "type": "integer", "example": 3 }, "mailboxes": { "type": "array", "description": "Mailboxes created for this domain.", "items": { "type": "object", "properties": { "mailbox_id": { "type": "string", "example": "01GHI..." }, "first_name": { "type": "string", "example": "Admin" }, "last_name": { "type": "string", "example": "User" }, "username": { "type": "string", "example": "admin@warmeddomain.com" }, "type": { "type": "string", "enum": [ "GOOGLE", "MICROSOFT" ], "example": "GOOGLE" }, "master_inbox": { "type": "boolean", "example": true } } } } } } }, "failed_domains": { "type": "array", "items": { "type": "object", "properties": { "domain_id": { "type": "string", "example": "pw-unavailable" }, "reason": { "type": "string", "example": "Domain is reserved by another user" } } } }, "total_successful": { "type": "integer", "example": 1 }, "total_failed": { "type": "integer", "example": 1 }, "total_mailboxes_created": { "type": "integer", "example": 3 }, "total_cost": { "type": "number", "example": 13.0 } } }, "message": { "type": "string", "example": "Pre-warm domains purchase completed" } } }, "example": { "success": true, "data": { "order_id": "01ABC...", "successful_domains": [ { "domain_id": "01DEF...", "domain_name": "warmeddomain.com", "domain_price": 5.5, "mailbox_count": 3, "mailboxes": [ { "mailbox_id": "01GHI...", "first_name": "Admin", "last_name": "User", "username": "admin@warmeddomain.com", "type": "GOOGLE", "master_inbox": true } ] } ], "failed_domains": [ { "domain_id": "pw-unavailable", "reason": "Domain is reserved by another user" } ], "total_successful": 1, "total_failed": 1, "total_mailboxes_created": 3, "total_cost": 13.0 }, "message": "Pre-warm domains purchase completed" } } } }, "400": { "$ref": "#/components/responses/400" }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Insufficient credits: available 5.00, required 13.00" } } } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/export": { "post": { "tags": [ "Export" ], "summary": "Export Mailboxes to Sequencer", "description": "Exports one or more mailboxes to a supported cold email sequencer.\n\nEach sequencer requires different credentials:\n\n| Sequencer | Required Fields |\n|---|---|\n| `instantly` | `api_key`, `username`, `password`, `app_workspace_name` |\n| `smartlead` | `username`, `password` |\n| `reachinbox` | `api_key`, `username`, `password`, `app_workspace_name` |\n| `emailbison` | `api_key` (super-admin token), `url`, `app_workspace_name`, `client_id` only for Google mailboxes |\n| `plusvibe` | `username`, `password`, `app_workspace_name`, `client_id` only for Google mailboxes |\n| `masterinbox` | `username`, `password`, `app_workspace_name` workspace ID of masterinbox |\n| `salesforge` | `username`, `password`, `app_workspace_name` |\n| `sendkit` | `api_key`, `username`, `password`, `app_workspace_name`, `client_id` only for Google mailboxes |\n| `outreachfox` | `api_key`, `app_workspace_name` workspace ID for outreachfox |\n| `other` | `name` (platform name, e.g. Emelia, Warmy, FirstQuadrant, Woodpecker, lemlist, Snov.io, Apollo.io, luella, SuperAGI, Reply). For platforms not listed above. `url`, `username`, `password`, `app_workspace_name`, `api_key` |\n\nThe export runs asynchronously — poll `GET /export/{exportId}` or subscribe to the `order.export.completed` webhook for the result.\n\n**Rate limit:** 1 req/s burst, 1 accepted export per mailbox per vendor per rolling 24 hours (each `mailbox_id` + `sequencer` pair is counted separately; refused or failed requests don't count; exports with `sequencer: \"other\"` are exempt)", "operationId": "exportMailboxes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mailbox_ids", "sequencer" ], "properties": { "mailbox_ids": { "type": "array", "description": "Mailbox IDs to export.", "items": { "type": "string", "format": "uuid" }, "example": [ "mbx_abc123", "mbx_def456" ] }, "sequencer": { "type": "string", "enum": [ "instantly", "smartlead", "reachinbox", "emailbison", "plusvibe", "masterinbox", "salesforge", "sendkit", "outreachfox", "other" ], "description": "Target sequencer platform. Use `other` for a platform not listed here.", "example": "instantly" }, "name": { "type": "string", "description": "Export name. **Required** for `sequencer: \"other\"` — name the target platform (e.g. Emelia, Warmy, FirstQuadrant, Woodpecker, lemlist, Snov.io, Apollo.io, luella, SuperAGI, Reply).", "example": "API Export" }, "username": { "type": "string", "description": "Sequencer account username. Required for `instantly`, `smartlead`, `reachinbox`, `plusvibe`, `masterinbox`, `salesforge`, `sendkit`. Optional for `other`.", "example": "user@example.com" }, "password": { "type": "string", "description": "Sequencer account password. Required for `instantly`, `smartlead`, `reachinbox`, `plusvibe`, `masterinbox`, `salesforge`, `sendkit`.", "example": "secret" }, "app_workspace_name": { "type": "string", "description": "Workspace name within the sequencer (which is the workspace ID for `masterinbox`, and your IceMail workspace ID for `outreachfox`). Required for `instantly`, `reachinbox`, `emailbison`, `plusvibe`, `masterinbox`, `salesforge`, `sendkit`, and `outreachfox`.", "example": "My Workspace" }, "api_key": { "type": "string", "description": "Sequencer API key. Required for `instantly`, `reachinbox`, `emailbison`, `sendkit`, and `outreachfox`. For `emailbison`, the token must be a `super-admin` token of the workspace you want to export into.", "example": "ebk_xxx" }, "url": { "type": "string", "format": "uri", "description": "Sequencer API base URL. Required for `emailbison`. For `plusvibe`, defaults to `https://app.plusvibe.ai/v2/login`.", "example": "https://emailbison.api.com" }, "client_id": { "type": "string", "description": "Google OAuth client ID. Required when exporting Google mailboxes via `emailbison`, `plusvibe`, or `sendkit`. Not needed for Microsoft mailboxes.", "example": "123456789.apps.googleusercontent.com" } } }, "examples": { "instantly": { "summary": "Export to Instantly", "value": { "mailbox_ids": [ "mbx_abc123", "mbx_def456" ], "sequencer": "instantly", "api_key": "inst_xxx", "username": "user@example.com", "password": "secret", "app_workspace_name": "My Workspace" } }, "smartlead": { "summary": "Export to Smartlead", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "smartlead", "username": "user@example.com", "password": "secret" } }, "reachinbox": { "summary": "Export to Reachinbox", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "reachinbox", "username": "user@example.com", "password": "secret", "app_workspace_name": "My Workspace", "api_key": "rbx_xxx" } }, "emailbison": { "summary": "Export to Emailbison (Google mailboxes)", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "emailbison", "api_key": "ebk_xxx", "url": "https://emailbison.api.com", "app_workspace_name": "My Workspace", "client_id": "123456789.apps.googleusercontent.com" } }, "plusvibe": { "summary": "Export to Plusvibe", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "plusvibe", "username": "user@example.com", "password": "secret", "app_workspace_name": "My Workspace", "client_id": "123456789.apps.googleusercontent.com" } }, "masterinbox": { "summary": "Export to Masterinbox (Google mailboxes)", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "masterinbox", "username": "user@example.com", "password": "secret", "app_workspace_name": "workspace_id_123" } }, "salesforge": { "summary": "Export to Salesforge", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "salesforge", "username": "user@example.com", "password": "secret", "app_workspace_name": "My Workspace" } }, "sendkit": { "summary": "Export to Sendkit (Google mailboxes)", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "sendkit", "username": "user@example.com", "password": "secret", "app_workspace_name": "My Workspace", "api_key": "skt_xxx", "client_id": "123456789.apps.googleusercontent.com" } }, "outreachfox": { "summary": "Export to OutreachFox", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "outreachfox", "api_key": "ofx_xxx", "app_workspace_name": "ws_abc123" } }, "other": { "summary": "Export to an unlisted platform (e.g. Emelia, Warmy, FirstQuadrant, Woodpecker, lemlist, Snov.io, Apollo.io, luella, SuperAGI, Reply)", "value": { "mailbox_ids": [ "mbx_abc123" ], "sequencer": "other", "name": "Emelia", "url": "https://app.emelia.io", "username": "user@example.com", "password": "secret" } } } } } }, "responses": { "201": { "description": "Export job created. `total` is the number of mailboxes queued for export. The export runs asynchronously — poll `GET /export/{exportId}` or subscribe to the `order.export.completed` webhook for the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "export_id": { "type": "string", "description": "Identifier of the created export.", "example": "01JF8XC1D2E3F4G5H6J7K8L9M0" }, "total": { "type": "integer", "description": "Number of mailboxes queued for export.", "example": 2 } } }, "message": { "type": "string", "example": "Mailbox export created successfully" } } }, "example": { "success": true, "data": { "success": true, "export_id": "01JF8XC1D2E3F4G5H6J7K8L9M0", "total": 2 }, "message": "Mailbox export created successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" }, "429": { "description": "One or more mailboxes in `mailbox_ids` are over their limit: already exported to this sequencer in the last 24 hours, or sent again within 1 second. Nothing was exported and no quota was used. `blocked` lists the ID of every limited mailbox. `retry_after` is the wait in seconds for the first one. Remove the `blocked` IDs, wait 1–2 seconds, and resend the rest.", "content": { "application/json": { "example": { "success": false, "message": "Too many requests. Please try again later.", "retry_after": 52340, "blocked": [ "mbx_abc123", "mbx_def456" ] } } } } } } }, "/export/{exportId}": { "get": { "tags": [ "Export" ], "summary": "Get Export Status", "description": "Returns the current status and progress of an export job.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "getExportStatus", "parameters": [ { "name": "exportId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Export job ID.", "example": "exp_01ABC..." } ], "responses": { "200": { "description": "Export job details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Export job ID.", "example": "exp_01ABC..." }, "name": { "type": "string", "description": "Export name.", "example": "Instantly export" }, "vendor": { "type": "string", "description": "Target sequencer.", "example": "instantly" }, "status": { "type": "string", "description": "Current status (`pending`, `processing`, `completed`, `failed`).", "example": "completed" }, "total": { "type": "integer", "description": "Total mailboxes in this export.", "example": 5 }, "processed": { "type": "integer", "description": "Mailboxes processed so far (successful + failed).", "example": 5 }, "format": { "type": "string", "description": "Export format.", "example": "json" }, "created_at": { "type": "string", "format": "date-time", "description": "When the export was created." }, "modified_at": { "type": "string", "format": "date-time", "description": "When the export was last updated." }, "success": { "type": "integer", "description": "Mailboxes exported successfully (`processed` - `failed`).", "example": 4 }, "failed": { "type": "integer", "description": "Mailboxes whose export job failed. Republishing the export retries these.", "example": 1 } } } } }, "example": { "success": true, "data": { "id": "exp_01ABC...", "name": "Instantly export", "vendor": "instantly", "status": "completed", "total": 5, "processed": 5, "format": "json", "created_at": "2026-03-21T10:00:00Z", "modified_at": "2026-03-21T10:01:00Z", "success": 4, "failed": 1 } } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/export/republish/{exportId}": { "post": { "tags": [ "Export" ], "summary": "Republish Export (Retry Failed Export)", "description": "Retries or resumes a failed/stuck export. Automatically detects the stuck stage and resumes appropriately.\n\n**Cooldown:** Once republished, the same export cannot be republished again for **2 hours** (returns 429).\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained (general rate limit, workspace-scoped)", "operationId": "republishExport", "parameters": [ { "name": "exportId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Export job ID to republish.", "example": "exp_01ABC..." } ], "responses": { "200": { "description": "Export republished successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "stage": "export_failed_jobs", "retried": 7, "mailbox_ids": [ "01K5J0JV0ERRAXGHM5TJ29EG2P", "01K5J0JV0D4EAOLFE095CN58207", "01K5J0JV0D1SP3WIFKSBC3GHPEJ" ] }, "message": "created 3 retry batch(es), dispatch initiated in background" } } } }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "description": "Republish cooldown active (2 hours) or rate limit exceeded.", "content": { "application/json": { "example": { "success": false, "message": "Export was recently republished. Please wait 2 hours before retrying.", "retry_after": 7200 } } } } } } }, "/lookup/mailboxes": { "post": { "tags": [ "Lookup" ], "summary": "Resolve Mailbox IDs by Username", "description": "Resolves a batch of mailbox usernames (full email addresses, e.g. `john@example.com`) to their mailbox IDs within the workspace. Each requested username is returned as a key; unknown usernames resolve to `null`.\n\n**Validation:** `usernames` must be a non-empty array of 1–100 non-empty strings.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "lookupMailboxIds", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "usernames" ], "properties": { "usernames": { "type": "array", "items": { "type": "string" }, "description": "Full mailbox email addresses to resolve (1–100). Matched exactly, so send them as stored (lowercase, no spaces). A bare name like `john` never matches.", "example": [ "john@example.com", "jane@example.com", "unknown@example.com" ] } } } } } }, "responses": { "200": { "description": "Mailbox IDs resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "john@example.com": "01JF8XA1B2C3D4E5F6G7H8J9K0", "jane@example.com": "01JF8XA2B3C4D5E6F7G8H9J0K1", "unknown@example.com": null }, "message": "Mailbox IDs resolved successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/lookup/domains": { "post": { "tags": [ "Lookup" ], "summary": "Resolve Domain IDs by Name", "description": "Resolves a batch of domain names to their domain IDs within the workspace. Each requested domain name is returned as a key; unknown domains resolve to `null`.\n\n**Validation:** `domains` must be a non-empty array of 1–100 non-empty strings.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "lookupDomainIds", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Domain names to resolve (1–100).", "example": [ "example.com", "notmine.com" ] } } } } } }, "responses": { "200": { "description": "Domain IDs resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "example.com": "01JF8XB1C2D3E4F5G6H7J8K9L0", "notmine.com": null }, "message": "Domain IDs resolved successfully" } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } } }, "/webhook": { "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook Endpoint", "description": "Creates a webhook endpoint for the workspace. Omitting `subscribed_events` (or passing `[]`) subscribes the endpoint to **all events** by default.\n\n**Limit:** Maximum of 5 webhook endpoints per workspace.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that will receive webhook events.", "example": "https://example.com/hooks/mail-events" }, "description": { "type": "string", "description": "Optional label to identify the webhook.", "example": "Production order events" }, "subscribed_events": { "type": "array", "items": { "type": "string" }, "description": "Event ids to subscribe to. Omit or pass `[]` to subscribe to all events.", "example": [ "order.mailbox.active", "order.mailbox.failed" ] }, "format": { "type": "string", "enum": [ "json" ], "default": "json", "description": "Payload format. Only 'json' is supported currently." } } } } } }, "responses": { "201": { "description": "Webhook endpoint created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Webhook endpoint created successfully", "data": { "id": "01JF8XD1E2F3G4H5J6K7L8M9N0", "workspace_id": "ws_abc123", "url": "https://example.com/hooks/mail-events", "description": "Production order events", "is_active": true, "subscribed_events": [ "order.mailbox.active", "order.mailbox.failed" ], "format": "json", "created_at": "2026-04-17T10:00:00.000Z", "updated_at": "2026-04-17T10:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "get": { "tags": [ "Webhooks" ], "summary": "List Webhook Endpoints", "description": "Returns all webhook endpoints configured for the workspace.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "listWebhooks", "responses": { "200": { "description": "List of webhook endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "format": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "success": true, "data": [ { "id": "01JF8XD1E2F3G4H5J6K7L8M9N0", "workspace_id": "ws_abc123", "url": "https://example.com/hooks/mail-events", "description": "Production order events", "is_active": true, "subscribed_events": [ "order.mailbox.active", "order.mailbox.failed" ], "format": "json", "created_at": "2026-04-17T10:00:00.000Z", "updated_at": "2026-04-17T10:00:00.000Z" } ] } } } }, "403": { "$ref": "#/components/responses/403" } } } }, "/webhook/{webhookId}": { "put": { "tags": [ "Webhooks" ], "summary": "Update Webhook Endpoint", "description": "Updates a webhook endpoint. All fields are optional; only the fields provided are changed. Passing `subscribed_events: []` switches the endpoint back to subscribing to all events.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "updateWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID.", "example": "01JF8XD1E2F3G4H5J6K7L8M9N0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/hooks/mail-events-v2" }, "is_active": { "type": "boolean", "example": false }, "description": { "type": "string", "example": "Production order events (v2)" }, "subscribed_events": { "type": "array", "items": { "type": "string" }, "example": [ "order.mailbox.active", "order.mailbox.failed" ] }, "format": { "type": "string", "enum": [ "json" ] } } } } } }, "responses": { "200": { "description": "Webhook endpoint updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Webhook endpoint updated successfully", "data": { "id": "01JF8XD1E2F3G4H5J6K7L8M9N0", "workspace_id": "ws_abc123", "url": "https://example.com/hooks/mail-events-v2", "description": "Production order events (v2)", "is_active": false, "subscribed_events": [ "order.mailbox.active", "order.mailbox.failed" ], "format": "json", "created_at": "2026-04-17T10:00:00.000Z", "updated_at": "2026-04-17T11:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/400" }, "403": { "$ref": "#/components/responses/403" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook Endpoint", "description": "Deletes a webhook endpoint. Its delivery history is deleted along with it.\n\n**Rate limit:** 5 req/s burst, 30 req/min sustained", "operationId": "deleteWebhook", "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID.", "example": "01JF8XD1E2F3G4H5J6K7L8M9N0" } ], "responses": { "200": { "description": "Webhook endpoint deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Webhook endpoint deleted successfully", "data": null } } } }, "403": { "$ref": "#/components/responses/403" } } } } } }