Icemail API

Introduction

The Icemail API provides programmatic access to manage your email infrastructure — domains, mailboxes, DNS records, workspaces, and billing.

Getting Started

Step 1 — Obtain your API Key

Log into your [Icemail Dashboard](https://icemail.ai), navigate to Settings > API Keys, and click Generate New Key.

> Important: Keep your API key secret. Never expose it in frontend code or public repositories.

Step 2 — Make your first request

Verify your API key by listing your workspaces:

curl -X GET https://app.icemail.ai/api/v1/workspace \
  -H "x-api-key: YOUR_API_KEY"

A successful response will return 200 with your workspace data.

Authentication

All requests require your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

Requests without a valid key will return 403 Forbidden.

Base URL

https://app.icemail.ai/api/v1

Pagination

All list endpoints support pagination:

| Parameter | Default | Max | Description |

|---|---|---|---|

| `page` | 1 | — | Page number |

| `limit` | 10 | 50 | Items per page |

| `search` | — | — | Filter results (varies by endpoint) |

Example: GET /domain?page=2&limit=5&search=example

Roles & Permissions

Icemail uses role-based access control (RBAC). Each workspace member is assigned one of the following roles:

| Role | Description |

|---|---|

| **OWNER** | Full access — manage billing, invite users, and modify all resources. |

| **ADMIN** | Same as Owner, except cannot delete the workspace. |

| **EDITOR** | Manage domains, DNS, mailboxes, and forwarding. Cannot modify billing or invite users. |

| **VIEWER** | Read-only access to all resources. |

Permission requirements are noted on each endpoint below.

Response Format

All endpoints return a consistent JSON structure:

Success (200 / 201)

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

Error (4xx)

{
  "success": false,
  "message": "Description of what went wrong",
  "errors": [{ "field": "name", "message": "name is required" }]
}

Error Codes

| Code | Meaning | Common Cause |

|---|---|---|

| `400` | Bad Request | Missing required fields or invalid data |

| `403` | Forbidden | Invalid API key or insufficient permissions |

| `404` | Not Found | Resource ID does not exist |

| `409` | Conflict | Duplicate entry (e.g. user already invited) |

Rate Limiting

All v1 API endpoints are rate-limited using a dual-window system (burst + sustained) to prevent abuse while allowing normal usage patterns.

Default Limits

| Endpoint Pattern | Burst (per second) | Sustained (per minute) |

|---|---|---|

| `POST /v1/export` | 1 req/s | 1 req/day (per mailbox, per vendor — unlimited for `sequencer: other`) |

| `GET /v1/export/:id` | 5 req/s | 30 req/min |

| `GET /v1/mailbox/:id/auth` | 5 req/s | 30 req/min |

| `PUT /v1/mailbox/*` | 5 req/s | 20 req/min |

| `* /v1/domain/:id/dns-records` | 5 req/s | 20 req/min |

| `PUT,DELETE /v1/domain/forwarding,dmarc` | 1 req/s | 10 req/min |

| `POST /v1/order` | 1 req/5s | 12 req/min |

| `POST /v1/wallet/topup` | 1 req/10s | 20 req/min |

| `POST /v1/prewarm/buy` | 1 req/5s | 12 req/min |

| `* /v1/prewarm*` | 5 req/s | 30 req/min |

| `* /v1/domain*` | 5 req/s | 30 req/min |

| `* /v1/mailbox*` | 5 req/s | 30 req/min |

| All other endpoints | 5 req/s | 30 req/min |

Entity-Scoped Limits

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.

Only 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.

Response Headers

Every response includes rate limit headers based on the sustained (per-minute) window:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 25
X-RateLimit-Reset: 1700000060

Rate Limit Exceeded (429)

When rate limited, a Retry-After header is also included:

Retry-After: 60

{
  \"success\": false,
  \"message\": \"Too many requests. Please try again later.\",
  \"retry_after\": 60
}

For 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.

Permission Matrix

| Endpoint | OWNER | ADMIN | EDITOR | VIEWER |

|---|---|---|---|---|

| GET /v1/workspace | Yes | Yes | Yes | Yes |

| POST /v1/workspace | Yes | Yes | No | No |

| PUT /v1/workspace | Yes | Yes | No | No |

| POST /v1/workspace/invite | Yes | Yes | No | No |

| GET /v1/wallet | Yes | Yes | Yes | Yes |

| PUT /v1/wallet/auto-topup | Yes | Yes | No | No |

| POST /v1/wallet/topup | Yes | Yes | No | No |

| GET /v1/domain | Yes | Yes | Yes | Yes |

| GET /v1/domain/available | Yes | Yes | Yes | Yes |

| GET /v1/domain/:id | Yes | Yes | Yes | Yes |

| GET /v1/domain/ns-records | Yes | Yes | Yes | Yes |

| GET /v1/domain/:id/dns-records | Yes | Yes | Yes | Yes |

| POST /v1/domain/:id/dns-records | Yes | Yes | Yes | No |

| PUT /v1/domain/:id/dns-records | Yes | Yes | Yes | No |

| PUT /v1/domain/:id/forwarding | Yes | Yes | Yes | No |

| PUT /v1/domain/:id/dmarc | Yes | Yes | Yes | No |

| PUT /v1/domain/forwarding | Yes | Yes | Yes | No |

| PUT /v1/domain/dmarc | Yes | Yes | Yes | No |

| POST /v1/domain/add-google-client-id | Yes | Yes | Yes | No |

| DELETE /v1/domain/forwarding | Yes | Yes | Yes | No |

| DELETE /v1/domain/dmarc | Yes | Yes | Yes | No |

| DELETE /v1/domain/mailboxes | Yes | Yes | Yes | No |

| DELETE /v1/domain/clear-dns | Yes | Yes | Yes | No |

| DELETE /v1/domain | Yes | Yes | Yes | No |

| GET /v1/mailbox | Yes | Yes | Yes | Yes |

| GET /v1/mailbox/:id | Yes | Yes | Yes | Yes |

| GET /v1/mailbox/domain/:id | Yes | Yes | Yes | Yes |

| GET /v1/mailbox/price | Yes | Yes | Yes | Yes |

| PUT /v1/mailbox/:id | Yes | Yes | Yes | No |

| PUT /v1/mailbox/forwarding | Yes | Yes | Yes | No |

| DELETE /v1/mailbox/forwarding | Yes | Yes | Yes | No |

| GET /v1/mailbox/:id/auth | Yes | Yes | Yes | Yes |

| GET /v1/mailbox/:id/app-password | Yes | Yes | Yes | Yes |

| POST /v1/order | Yes | Yes | Yes | No |

| GET /v1/prewarm | Yes | Yes | Yes | Yes |

| POST /v1/prewarm/buy | Yes | Yes | Yes | No |

| POST /v1/export | Yes | Yes | Yes | No |

| GET /v1/export/:id | Yes | Yes | Yes | Yes |

| POST /v1/export/republish/:id | Yes | Yes | Yes | No |

| POST /v1/lookup/mailboxes | Yes | Yes | Yes | Yes |

| POST /v1/lookup/domains | Yes | Yes | Yes | Yes |

| GET /v1/webhook | Yes | Yes | Yes | Yes |

| POST /v1/webhook | Yes | Yes | No | No |

| PUT /v1/webhook/:id | Yes | Yes | No | No |

| DELETE /v1/webhook/:id | Yes | Yes | No | No |

Support

Visit [icemail.ai](https://icemail.ai) or contact our support team for assistance.

Base URL: https://app.icemail.ai/api/v1

Workspace

Workspaces are the top-level container in Icemail. All domains, mailboxes, and billing are scoped to a workspace.

Use these endpoints to create and update workspaces, and to invite team members with role-based access.

GET /workspace

List Workspaces

Returns all workspaces accessible by the authenticated API key.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/workspace

Responses

POST /workspace

Create Workspace

Creates a new workspace.

A 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.

Rate limit: 5 req/s burst, 30 req/min sustained

POST https://app.icemail.ai/api/v1/workspace

Request body (application/json, required)

{
  "name": "My New Workspace"
}

Responses

PUT /workspace

Update Workspace

Renames the current workspace.

Rate limit: 5 req/s burst, 30 req/min sustained

PUT https://app.icemail.ai/api/v1/workspace

Request body (application/json, required)

{
  "name": "Updated Workspace Name"
}

Responses

POST /workspace/invite

Invite User to Workspace

Sends an email invitation to join the workspace with the specified role.

Assignable roles: ADMIN, EDITOR, VIEWER

Returns 409 if the user is already a workspace member.

Rate limit: 5 req/s burst, 30 req/min sustained

POST https://app.icemail.ai/api/v1/workspace/invite

Request body (application/json, required)

{
  "email": "teammate@company.com",
  "role": "EDITOR"
}

Responses

Wallet

The wallet manages your workspace's credit balance and auto top-up configuration.

Credits are consumed when provisioning domains, mailboxes, and other billable resources.

GET /wallet

Get Wallet Balance

Returns the current wallet balance and auto top-up configuration.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/wallet

Responses

PUT /wallet/auto-topup

Configure Auto Top-up

Enables or disables automatic wallet recharging.

When enabled, the wallet is topped up by topup_amount whenever the balance drops below threshold.

Rate limit: 5 req/s burst, 30 req/min sustained

PUT https://app.icemail.ai/api/v1/wallet/auto-topup

Request body (application/json, required)

{
  "enabled": true,
  "threshold": 10,
  "topup_amount": 50
}

Responses

POST /wallet/topup

Top-up Wallet

Adds credits to the workspace wallet.

> Note: After payment, check GET /wallet for the updated balance. No polling needed.

Amount: $1–$10,000 USD

Rate limit: 1 req/10s burst, 20 req/min sustained (workspace-scoped)

POST https://app.icemail.ai/api/v1/wallet/topup

Request body (application/json, required)

{
  "amount": 50
}

Responses

Domain

Domains are the foundation of your email infrastructure. Each domain supports DNS records, URL forwarding, and DMARC policies.

Bulk endpoints are available for applying forwarding and DMARC settings across multiple domains simultaneously.

Domain Termination Flow

Winding a domain down is a three-stage process. Each stage has its own endpoint; pick the stage that matches what you want to do.

| Stage | Endpoint | What it ends | What survives |

|---|---|---|---|

| 1. Delete Mailboxes | `DELETE /domain/mailboxes` | Every mailbox on the domain | The domain row + its DNS zone (records may stay too) |

| 2. Clear DNS Records | `DELETE /domain/clear-dns` | All MX / SPF / DKIM / DMARC / forwarding records | The zone itself + the Domains row — ready to reuse |

| 3. Delete Domains | `DELETE /domain` | The Domains row + ClouDNS zone + leftover inactive mailbox history | Nothing — the domain is removed from your listing (permanent) |

Common flows:

Each endpoint enforces preconditions and silently skips domains that don't qualify (rather than erroring the whole batch) — call the missing stage first and retry.

GET /domain/available

Check Domain Availability

Checks whether a domain is available for purchase and returns pricing information along with recommended alternatives.

Validation:

Rate limit: 5 req/s burst, 30 req/min sustained (global domain rate limit)

GET https://app.icemail.ai/api/v1/domain/available

Parameters

Responses

GET /domain/{domainId}

Get Domain by ID

Returns details for a specific domain.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/domain/{domainId}

Parameters

Responses

GET /domain/ns-records

Fetch Nameservers

Returns the Icemail nameservers (NS records) that your domains should point to at your registrar.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/domain/ns-records

Responses

GET /domain/{domainId}/dns-records

Get DNS Records

Returns all DNS records for a domain.

Rate limit: 5 req/s burst, 20 req/min sustained

GET https://app.icemail.ai/api/v1/domain/{domainId}/dns-records

Parameters

Responses

POST /domain/{domainId}/dns-records

Create DNS Records

Creates one or more DNS records for a domain.

Supported types: A, AAAA, CNAME, MX, TXT, NS, SRV, PTR, HTTPS, SVCB, TLSA, CAA

Use @ as the name to target the root domain.

Rate limit: 5 req/s burst, 20 req/min sustained

POST https://app.icemail.ai/api/v1/domain/{domainId}/dns-records

Parameters

Request body (application/json, required)

{
  "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"
    }
  ]
}

Responses

PUT /domain/{domainId}/dns-records

Update DNS Records

Updates existing DNS records. Each record in the array must include its id.

Use GET /domain/{domainId}/dns-records to retrieve record IDs.

Rate limit: 5 req/s burst, 20 req/min sustained

PUT https://app.icemail.ai/api/v1/domain/{domainId}/dns-records

Parameters

Request body (application/json, required)

{
  "records": [
    {
      "id": "rec_001",
      "type": "A",
      "name": "@",
      "content": "5.6.7.8"
    }
  ]
}

Responses

PUT /domain/{domainId}/forwarding

Update Domain Forwarding

Sets a forwarding URL for a domain. Visitors to this domain will be redirected to the specified URL.

Rate limit: 5 req/s burst, 30 req/min sustained

PUT https://app.icemail.ai/api/v1/domain/{domainId}/forwarding

Parameters

Request body (application/json, required)

{
  "forwarding_url": "https://example.com",
  "mask": true
}

Responses

PUT /domain/{domainId}/dmarc

Update DMARC Record

Configures DMARC for a domain by setting the email that receives aggregate reports.

DMARC (Domain-based Message Authentication, Reporting & Conformance) helps prevent email spoofing.

Rate limit: 5 req/s burst, 30 req/min sustained

PUT https://app.icemail.ai/api/v1/domain/{domainId}/dmarc

Parameters

Request body (application/json, required)

{
  "dmarc_email": "dmarc-reports@example.com"
}

Responses

PUT /domain/forwarding

Bulk Assign Forwarding

Applies the same forwarding URL to multiple domains in a single request.

Rate limit: 1 req/s burst, 10 req/min sustained

PUT https://app.icemail.ai/api/v1/domain/forwarding

Request body (application/json, required)

{
  "domain_ids": [
    "dom_abc123",
    "dom_def456"
  ],
  "forwarding_url": "https://example.com",
  "mask": true
}

Responses

DELETE /domain/forwarding

Bulk Remove Forwarding

Removes forwarding configuration from multiple domains.

Rate limit: 1 req/s burst, 10 req/min sustained

DELETE https://app.icemail.ai/api/v1/domain/forwarding

Request body (application/json, required)

{
  "domain_ids": [
    "dom_abc123",
    "dom_def456"
  ]
}

Responses

PUT /domain/dmarc

Bulk Assign DMARC

Applies the same DMARC reporting email to multiple domains.

Rate limit: 1 req/s burst, 10 req/min sustained

PUT https://app.icemail.ai/api/v1/domain/dmarc

Request body (application/json, required)

{
  "domain_ids": [
    "dom_abc123",
    "dom_def456"
  ],
  "dmarc_email": "dmarc-reports@example.com"
}

Responses

DELETE /domain/dmarc

Bulk Remove DMARC

Removes DMARC configuration from multiple domains. DMARC reports will no longer be sent for these domains.

Rate limit: 1 req/s burst, 10 req/min sustained

DELETE https://app.icemail.ai/api/v1/domain/dmarc

Request body (application/json, required)

{
  "domain_ids": [
    "dom_abc123",
    "dom_def456"
  ]
}

Responses

POST /domain/add-google-client-id

Add Google OAuth Client ID

Pushes a Google OAuth client_id to the master inbox of each given domain (queues a CLIENTID export job per domain).

Each domain has a 15-minute cooldown — a domain processed within the last 15 minutes is returned under skipped instead of being re-queued.

The job runs asynchronously — subscribe to the order.client_id.completed / order.client_id.failed webhooks for the per-mailbox result.

Rate limit: 5 req/s burst, 30 req/min sustained

POST https://app.icemail.ai/api/v1/domain/add-google-client-id

Request body (application/json, required)

{
  "client_id": "1234567890-abcdef.apps.googleusercontent.com",
  "domain_ids": [
    "01DEF...",
    "01GHI..."
  ]
}

Responses

DELETE /domain/mailboxes

Delete Mailboxes by Domain

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.

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.

Modes:

> Notes:

> - skipped: true on a per_domain entry means the domain had no active mailboxes — nothing to do.

> - error: "<message>" 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.

> - For scheduled mode the resolved date must be in the future. Domains whose next_billing_date is already past must use mode: "immediate".

Rate limit: 5 req/s burst, 30 req/min sustained

DELETE https://app.icemail.ai/api/v1/domain/mailboxes

Request body (application/json, required)

{
  "domain_ids": [
    "01DEF...",
    "01GHI..."
  ],
  "mode": "immediate"
}

Responses

DELETE /domain/clear-dns

Clear DNS Records

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.

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.

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.

Per-domain preconditions enforced by the worker (silently skipped if not met):

Async: responds 202 immediately with a correlation_id. Processing typically completes in 10–15 minutes.

Rate limit: 5 req/s burst, 30 req/min sustained

DELETE https://app.icemail.ai/api/v1/domain/clear-dns

Request body (application/json, required)

{
  "domain_ids": [
    "01DEF...",
    "01GHI..."
  ]
}

Responses

DELETE /domain

Delete Domains

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.

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.

Per-domain preconditions enforced by the worker (silently skipped if not met):

Async: responds 202 immediately with a correlation_id. Processing typically completes in 10–15 minutes.

> Warning: This is destructive. The Domains row and all linked inactive mailboxes are permanently deleted and are no longer queryable through the public API.

Rate limit: 5 req/s burst, 30 req/min sustained

DELETE https://app.icemail.ai/api/v1/domain

Request body (application/json, required)

{
  "domain_ids": [
    "01DEF...",
    "01GHI..."
  ]
}

Responses

GET /domain

List Domains

Returns all domains in the workspace with pagination and optional search.

The search parameter performs a case-insensitive partial match on the domain name.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/domain

Parameters

Responses

Mailbox

Mailboxes represent individual email accounts associated with your domains (e.g. john@yourdomain.com).

Each mailbox can be configured with forwarding rules and supports 2FA authenticator code retrieval.

GET /mailbox

List Mailboxes

Returns all mailboxes in the workspace with pagination, search, and provider filtering.

The search parameter matches against first_name, last_name, and username.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/mailbox

Parameters

Responses

GET /mailbox/price

Get Mailbox Prices

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.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/mailbox/price

Responses

GET /mailbox/{mailboxId}

Get Mailbox by ID

Returns details for a specific mailbox.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/mailbox/{mailboxId}

Parameters

Responses

PUT /mailbox/{mailboxId}

Update Mailbox Details

Updates a mailbox's display name, username, or profile picture. At least one field must be provided.

Changing username will change the email address (e.g. john@example.com becomes jane@example.com).

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.

Rate limit: 5 req/s burst, 20 req/min sustained

PUT https://app.icemail.ai/api/v1/mailbox/{mailboxId}

Parameters

Request body (application/json, required)

{
  "first_name": "John",
  "last_name": "Doe"
}

Responses

GET /mailbox/domain/{domainId}

Get Mailboxes by Domain

Returns all mailboxes belonging to a specific domain.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/mailbox/domain/{domainId}

Parameters

Responses

PUT /mailbox/forwarding

Bulk Update Mailbox Forwarding

Sets the same forwarding email for multiple mailboxes. Incoming mail to these mailboxes will be forwarded to the specified address.

Rate limit: 5 req/s burst, 20 req/min sustained

PUT https://app.icemail.ai/api/v1/mailbox/forwarding

Request body (application/json, required)

{
  "mailbox_ids": [
    "mbx_abc123",
    "mbx_def456"
  ],
  "forward_email": "team-inbox@company.com"
}

Responses

DELETE /mailbox/forwarding

Bulk Delete Mailbox Forwarding

Removes email forwarding for the given mailboxes at the provider and clears forward_email. Processed asynchronously (takes a few minutes to propagate).

CUSTOM mailboxes are skipped — they have no provider forwarding rule. If every id is a CUSTOM mailbox (or none match the workspace), returns 400.

Rate limit: 5 req/s burst, 20 req/min sustained

DELETE https://app.icemail.ai/api/v1/mailbox/forwarding

Request body (application/json, required)

{
  "mailbox_ids": [
    "mbx_abc123",
    "mbx_def456"
  ]
}

Responses

GET /mailbox/{mailboxId}/auth

Get Authenticator Code

Returns the current 2FA TOTP code for a mailbox.

TOTP codes typically refresh every 30 seconds.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/mailbox/{mailboxId}/auth

Parameters

Responses

GET /mailbox/{mailboxId}/app-password

Get Mailbox App Password

Returns the decrypted Google app password for a GOOGLE mailbox, or null when unset.

Non-Google mailboxes return 400; unknown ids return 404.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/mailbox/{mailboxId}/app-password

Parameters

Responses

Order

Orders allow you to purchase new domains or import existing ones, and provision mailboxes — all in a single request.

Credits are deducted for each domain and mailbox created. Importing existing domains skips the domain charge.

POST /order

Create Order

Purchases new domains and provisions mailboxes, or imports existing domains and creates mailboxes — all in a single request.

> 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.

>

> Skip this if you use your own Cloudflare account — the domain keeps its Cloudflare nameservers.

> 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.

Bulk Providers (CUSTOM / AZURE)

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.

> 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.

Constraints:

An invalid password returns 400 with the rules in the error message. Example of a valid password: SecurePass1!.

Rate limit: 1 req/5s burst, 12 req/min sustained (workspace-scoped)

POST https://app.icemail.ai/api/v1/order

Request body (application/json, required)

{
  "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!"
        }
      ]
    }
  ]
}

Responses

Pre-Warm

Pre-warm domains to improve email deliverability before sending campaigns.

List and monitor domains that are in the pre-warming phase.

GET /prewarm

List Pre-Warm Domains

Returns all domains currently in the pre-warming phase with pagination and optional search.

The search parameter performs a case-insensitive partial match on the domain name.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/prewarm

Parameters

Responses

POST /prewarm/buy

Buy Pre-Warm Domains

Purchases one or more pre-warm domains. Credits are deducted for each domain and its associated mailboxes.

Returns details of successful and failed purchases.

> 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.

Rate limit: 1 req/5s burst, 12 req/min sustained (workspace-scoped)

POST https://app.icemail.ai/api/v1/prewarm/buy

Request body (application/json, required)

{
  "domain_ids": [
    "pw-domain-1",
    "pw-domain-2"
  ]
}

Responses

Export

Export mailboxes directly to supported cold email sequencers (Instantly, Smartlead, Reachinbox, Emailbison, Plusvibe, Masterinbox, Salesforge, Sendkit, OutreachFox), or to an unlisted platform via other.

Each export is rate-limited per mailbox, per vendor, per day to prevent abuse — exports with sequencer: "other" are unlimited.

POST /export

Export Mailboxes to Sequencer

Exports one or more mailboxes to a supported cold email sequencer.

Each sequencer requires different credentials:

| Sequencer | Required Fields |

|---|---|

| `instantly` | `api_key`, `username`, `password`, `app_workspace_name` |

| `smartlead` | `username`, `password` |

| `reachinbox` | `api_key`, `username`, `password`, `app_workspace_name` |

| `emailbison` | `api_key` (super-admin token), `url`, `app_workspace_name`, `client_id` only for Google mailboxes |

| `plusvibe` | `username`, `password`, `app_workspace_name`, `client_id` only for Google mailboxes |

| `masterinbox` | `username`, `password`, `app_workspace_name` workspace ID of masterinbox |

| `salesforge` | `username`, `password`, `app_workspace_name` |

| `sendkit` | `api_key`, `username`, `password`, `app_workspace_name`, `client_id` only for Google mailboxes |

| `outreachfox` | `api_key`, `app_workspace_name` workspace ID for outreachfox |

| `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` |

The export runs asynchronously — poll GET /export/{exportId} or subscribe to the order.export.completed webhook for the result.

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)

POST https://app.icemail.ai/api/v1/export

Request body (application/json, required)

{
  "mailbox_ids": [
    "mbx_abc123",
    "mbx_def456"
  ],
  "sequencer": "instantly",
  "api_key": "inst_xxx",
  "username": "user@example.com",
  "password": "secret",
  "app_workspace_name": "My Workspace"
}

Responses

GET /export/{exportId}

Get Export Status

Returns the current status and progress of an export job.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/export/{exportId}

Parameters

Responses

POST /export/republish/{exportId}

Republish Export (Retry Failed Export)

Retries or resumes a failed/stuck export. Automatically detects the stuck stage and resumes appropriately.

Cooldown: Once republished, the same export cannot be republished again for 2 hours (returns 429).

Rate limit: 5 req/s burst, 30 req/min sustained (general rate limit, workspace-scoped)

POST https://app.icemail.ai/api/v1/export/republish/{exportId}

Parameters

Responses

Lookup

Resolve human-readable identifiers to Icemail resource IDs in bulk.

Map 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.

POST /lookup/mailboxes

Resolve Mailbox IDs by Username

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.

Validation: usernames must be a non-empty array of 1–100 non-empty strings.

Rate limit: 5 req/s burst, 30 req/min sustained

POST https://app.icemail.ai/api/v1/lookup/mailboxes

Request body (application/json, required)

{
  "usernames": [
    "john@example.com",
    "jane@example.com",
    "unknown@example.com"
  ]
}

Responses

POST /lookup/domains

Resolve Domain IDs by Name

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.

Validation: domains must be a non-empty array of 1–100 non-empty strings.

Rate limit: 5 req/s burst, 30 req/min sustained

POST https://app.icemail.ai/api/v1/lookup/domains

Request body (application/json, required)

{
  "domains": [
    "example.com",
    "notmine.com"
  ]
}

Responses

Webhooks

Overview

A 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.

Setting Up Webhooks

To configure a webhook, navigate to Settings > Notification > Add Webhook URL in the dashboard.

You will need to provide:

Retry Behavior

If 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.

Controlling Which Events Fire

| Event |

|---|

| `order.mailbox.active` |

| `order.mailbox.failed` |

| `order.domain.active` |

| `order.domain.failed` |

| `order.export.completed` |

| `order.mailbox.deleted` |

| `order.mailbox.renewed` |

| `mailbox.renewal.reminder` |

| `domain.renewal.reminder` |

| `mailbox.app_password.updated` |

| `order.client_id.completed` |

| `order.client_id.failed` |

Managing Webhooks via the API

In addition to the dashboard, webhook endpoints can be fully managed via the API:

| Method | Endpoint | Required Role |

|---|---|---|

| `POST` | `/webhook` | OWNER, ADMIN |

| `GET` | `/webhook` | OWNER, ADMIN, EDITOR, VIEWER |

| `PUT` | `/webhook/{id}` | OWNER, ADMIN |

| `DELETE` | `/webhook/{id}` | OWNER, ADMIN |

Webhook Events

Every delivery uses the same envelope: event, timestamp, workspace_id, email (the workspace owner's email, resolved at dispatch time), and data (event-specific payload).

1. Mailbox Active (`order.mailbox.active`)

Triggered when all mailboxes in an order have been successfully created and are now active.

Trigger condition: Every mailbox in the order reaches ACTIVE status.

Sample Payload:

{
  "event": "order.mailbox.active",
  "timestamp": "2026-04-17T10:30:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "mailbox_count": 3,
    "mailboxes": [
      { "mailbox_id": "01JF8XA1B2C3D4E5F6G7H8J9K0", "username": "john@example.com" },
      { "mailbox_id": "01JF8XA2B3C4D5E6F7G8H9J0K1", "username": "jane@example.com" },
      { "mailbox_id": "01JF8XA3B4C5D6E7F8G9H0J1K2", "username": "mike@example.com" }
    ]
  }
}

2. Mailbox Failed (`order.mailbox.failed`)

Triggered when a mailbox creation fails during the provisioning process.

Trigger condition: A mailbox fails to be created by the vendor (Google, Microsoft, or Custom).

Sample Payload:

{
  "event": "order.mailbox.failed",
  "timestamp": "2026-04-17T10:35:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "failed_mailboxes": [
      {
        "mailbox_id": "01JF8XA4B5C6D7E8F9G0H1J2K3",
        "username": "alex@example.com",
        "error_message": "Mailbox creation failed: license limit reached",
        "error_code": "LICENSE_LIMIT"
      }
    ]
  }
}

3. Domain Active (`order.domain.active`)

Triggered when all domains in an order have been activated and DNS propagation is complete.

Trigger condition: Every domain in the order reaches ACTIVE status after nameserver verification.

Sample Payload:

{
  "event": "order.domain.active",
  "timestamp": "2026-04-17T11:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "domain_count": 2,
    "domains": [
      { "domain_id": "01JF8XB1C2D3E4F5G6H7J8K9L0", "domain": "example.com" },
      { "domain_id": "01JF8XB2C3D4E5F6G7H8J9K0L1", "domain": "example.io" }
    ]
  }
}

4. Domain Failed (`order.domain.failed`)

Triggered when one or more domain purchases or setups fail.

Trigger condition: A domain fails during purchase, DNS zone creation, or nameserver propagation.

Sample Payload:

{
  "event": "order.domain.failed",
  "timestamp": "2026-04-17T11:05:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "failed_domains": [
      {
        "domain_id": "01JF8XB3C4D5E6F7G8H9J0K1L2",
        "domain": "example.net",
        "error_message": "Domain purchase failed: payment declined"
      },
      {
        "domain_id": "01JF8XB4C5D6E7F8G9H0J1K2L3",
        "domain": "example.org",
        "error_message": "DNS zone creation failed: domain already exists"
      }
    ]
  }
}

5. Export Completed (`order.export.completed`)

Triggered 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).

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.

Sample Payload:

{
  "event": "order.export.completed",
  "timestamp": "2026-04-17T12:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "export_id": "01JF8XC1D2E3F4G5H6J7K8L9M0",
    "total": 4,
    "failed_count": 1,
    "completed_mailboxes": [
      { "mailbox_id": "01JF8XA1B2C3D4E5F6G7H8J9K0", "username": "john@example.com" },
      { "mailbox_id": "01JF8XA2B3C4D5E6F7G8H9J0K1", "username": "jane@example.com" }
    ],
    "failed_mailboxes": [
      { "mailbox_id": "01JF8XA3B4C5D6E7F8G9H0J1K2", "username": "mike@example.com", "error_message": "Export job failed: vendor rejected credentials" }
    ],
    "pending_mailboxes": [
      { "mailbox_id": "01JF8XA4B5C6D7E8F9G0H1J2K3", "username": "alex@example.com" }
    ]
  }
}

> 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.

6. Mailbox Deleted (`order.mailbox.deleted`)

Triggered when one or more mailboxes are deleted from a workspace.

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).

Sample Payload:

{
  "event": "order.mailbox.deleted",
  "timestamp": "2026-04-17T14:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "deleted_count": 2,
    "mailboxes": [
      { "mailbox_id": "01JF8XA1B2C3D4E5F6G7H8J9K0", "username": "john@example.com" },
      { "mailbox_id": "01JF8XA2B3C4D5E6F7G8H9J0K1", "username": "jane@example.com" }
    ]
  }
}

7. Domain Renewal Reminder (`domain.renewal.reminder`)

Triggered 30 days before a domain's registration expires as a reminder to renew.

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).

Sample Payload:

{
  "event": "domain.renewal.reminder",
  "timestamp": "2026-04-17T04:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "domain_id": "01JF8XB1C2D3E4F5G6H7J8K9L0",
    "domain": "example.com",
    "created_at": "2025-05-17T00:00:00.000Z",
    "expires_at": "2026-05-17T00:00:00.000Z",
    "days_until_expiry": 30
  }
}

8. App Password Updated (`mailbox.app_password.updated`)

Triggered whenever a mailbox's app password is set or updated.

Trigger condition: Fires when an app password is written via the internal provisioning callback (app-password setup completing for a Google mailbox).

Sample Payload:

{
  "event": "mailbox.app_password.updated",
  "timestamp": "2026-04-17T15:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "mailbox_id": "01JF8XA1B2C3D4E5F6G7H8J9K0",
    "username": "john@example.com",
    "app_password": "abcd efgh ijkl mnop"
  }
}

> Security note: app_password is the plaintext app password. Only endpoints you trust should be subscribed to this event.

9. Google Client ID Completed (`order.client_id.completed`)

Triggered when a Google OAuth client ID pushed via POST /domain/add-google-client-id has been added to a domain's master inbox.

Trigger condition: One event per master inbox queued by the request, once its setup succeeds.

Sample Payload:

{
  "event": "order.client_id.completed",
  "timestamp": "2026-04-17T16:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "domain_id": "01JF8XB1C2D3E4F5G6H7J8K9L0",
    "domain": "example.com"
  }
}

10. Google Client ID Failed (`order.client_id.failed`)

Triggered when pushing a Google OAuth client ID via POST /domain/add-google-client-id fails for a domain's master inbox.

Trigger condition: One event per master inbox queued by the request, if its setup fails.

Sample Payload:

{
  "event": "order.client_id.failed",
  "timestamp": "2026-04-17T16:00:00.000Z",
  "workspace_id": "ws_abc123",
  "email": "owner@example.com",
  "data": {
    "domain_id": "01JF8XB1C2D3E4F5G6H7J8K9L0",
    "domain": "example.com",
    "error_message": "Client ID setup failed"
  }
}

POST /webhook

Create Webhook Endpoint

Creates a webhook endpoint for the workspace. Omitting subscribed_events (or passing []) subscribes the endpoint to all events by default.

Limit: Maximum of 5 webhook endpoints per workspace.

Rate limit: 5 req/s burst, 30 req/min sustained

POST https://app.icemail.ai/api/v1/webhook

Request body (application/json, required)

{
  "url": "https://example.com/hooks/mail-events",
  "description": "Production order events",
  "subscribed_events": [
    "order.mailbox.active",
    "order.mailbox.failed"
  ],
  "format": "json"
}

Responses

GET /webhook

List Webhook Endpoints

Returns all webhook endpoints configured for the workspace.

Rate limit: 5 req/s burst, 30 req/min sustained

GET https://app.icemail.ai/api/v1/webhook

Responses

PUT /webhook/{webhookId}

Update Webhook Endpoint

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.

Rate limit: 5 req/s burst, 30 req/min sustained

PUT https://app.icemail.ai/api/v1/webhook/{webhookId}

Parameters

Request body (application/json, required)

{
  "url": "https://example.com/hooks/mail-events-v2",
  "is_active": false,
  "description": "Production order events (v2)",
  "subscribed_events": [
    "order.mailbox.active",
    "order.mailbox.failed"
  ],
  "format": "json"
}

Responses

DELETE /webhook/{webhookId}

Delete Webhook Endpoint

Deletes a webhook endpoint. Its delivery history is deleted along with it.

Rate limit: 5 req/s burst, 30 req/min sustained

DELETE https://app.icemail.ai/api/v1/webhook/{webhookId}

Parameters

Responses

Schemas

SuccessResponse

Standard success response.

ValidationError

Returned when the request body or query parameters fail validation.

PermissionError

Returned when the API key lacks the required role.

NotFoundError

Returned when the specified resource does not exist.

ConflictError

Returned when the operation would create a duplicate entry.

Workspace

A workspace — the top-level organizational unit in Icemail.

Wallet

Workspace billing wallet with balance and auto top-up settings.

Domain

A domain registered in your workspace.

DnsRecord

A DNS record associated with a domain.

Mailbox

An email mailbox (e.g. john@yourdomain.com). Returned by GET /mailbox and GET /mailbox/{id}.

DomainMailbox

Reduced mailbox shape returned by GET /mailbox/domain/{domainId}. Does not include password, the nested domains object, or billing fields; adds warmup_duration.

UpdatedMailbox

A mailbox entry returned by the update endpoints. The update is queued to the vendor, so status is UPDATING.

MailboxUpdateResult

Result of PUT /mailbox/{id} and PUT /mailbox/forwarding. Contains one entry per requested mailbox.

AuthCode

Current 2FA TOTP code. Returns null if 2FA is not configured on the mailbox.

BundlePlan

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.

MailboxPricing

Resolved mailbox pricing for the calling workspace — reflects any active pricing override, falling back to the tenant/plan default otherwise.