InboxWarm API documentation

Reference documentation for InboxWarm's REST API. Use this alongside the InboxWarm API Postman collection.

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

InboxWarm uses a mixed authentication scheme depending on the HTTP method:

GET

GET and DELETE requests — send your API key as the api_key query parameter.

POST

POST and PATCH requests — send your API key as an apiKey field inside the JSON body.

Generate and manage keys from Developer kit > API Integration in the InboxWarm app. Each key grants full account access across every endpoint below.

Example — GET request:

GET https://app.inboxwarm.ai/api/v1/email-accounts?api_key=YOUR_API_KEY

Example — POST request body:

{
  "apiKey": "YOUR_API_KEY",
  ...
}

Default limit is 20 requests/minute per API key. Check current usage anytime via GET /rate-limit — this call does not count against your quota.

Errors follow a consistent shape:

{
  "error_code": "validation_error",
  "message": "One or more fields are invalid.",
  "details": {}
}

Common error_code values: validation_error (400), not_found (404), conflict (409), unprocessable (422).

System

GET/healthHealth Check GET/rate-limitRate Limit Status

Email Accounts

GET/email-accountsList Email Accounts POST/email-accountsConnect Email Account POST/email-accounts/bulk-connectBulk Connect Email Accounts POST/email-accounts/{emailAccountId}/disconnectDisconnect Email Account DELETE/email-accounts/{emailAccountId}Delete Email Account POST/email-accounts/bulk-deleteBulk Delete Email Accounts GET/email-accounts/{emailAccountId}/statusGet Email Account Status POST/email-accounts/bulk-statusBulk Email Account Status

Warmup

GET/warmup-settings/{emailAccountId}Get Warmup Settings PATCH/warmup-settings/{emailAccountId}Update Warmup Settings GET/warmup-settings/languagesList Warmup Languages GET/warmup-settings/industriesList Warmup Industries POST/warmup-settings/{emailAccountId}/startStart Warmup POST/warmup-settings/{emailAccountId}/stopStop Warmup POST/warmup-settings/bulk-actionBulk Warmup Action POST/warmup-settings/bulk-updateBulk Update Warmup Settings GET/warmup-status/{emailAccountId}Warmup Activity History

Deliverability

GET/setup-score/{emailAccountId}Get Setup Score POST/setup-score/{emailAccountId}/refreshRefresh Setup Score GET/dns-health/{emailAccountId}DNS Health Check POST/deliverability-score/{emailAccountId}Get Deliverability Score

Reports

GET/dashboardDashboard POST/reportsSingle Account Report POST/reports/bulkBulk Report POST/reports/exportExport Report

GEThttps://app.inboxwarm.ai/api/v1/health

Basic liveness check for the API.

Auth:query parameterapi_key

Responses

{
  "status": "ok"
}

GEThttps://app.inboxwarm.ai/api/v1/rate-limit

Check current rate-limit consumption without using up a request against your quota.

Auth:query parameterapi_key

Responses

{
  "limit": 20,
  "remaining": 18,
  "reset": 1752585600
}

GEThttps://app.inboxwarm.ai/api/v1/email-accounts

List connected email accounts with their current status. Supports search, pagination, and sorting. Use search to look up the emailAccountId for an address if you ever need to re-resolve it.

Auth:query parameterapi_key

Query parameters

searchSearch by email address or name

statusactive | warming | paused | error | auth-expired

sort

sortBy

Responses

{
  "items": [
    {
      "id": "12345",
      "fromEmail": "john@yourcompany.com",
      "fromName": "John Doe",
      "type": "gmail",
      "status": "warming",
      "createdAt": "2026-06-01T10:00:00.000Z"
    },
    {
      "id": "12346",
      "fromEmail": "sales@yourcompany.com",
      "fromName": "Sales Team",
      "type": "microsoft",
      "status": "active",
      "createdAt": "2026-06-03T14:20:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POSThttps://app.inboxwarm.ai/api/v1/email-accounts

Connect a Gmail, Microsoft, or SMTP/IMAP account using SMTP/IMAP credentials (an app password works for Gmail and Microsoft). Store the returned emailAccountId — every other endpoint is keyed off it.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "fromEmail": "john@yourcompany.com",
  "fromName": "John Doe",
  "type": "gmail",
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "password": "your-password",
    "encryption": "TLS",
    "userName": "smtp-username"
  },
  "imap": {
    "host": "imap.example.com",
    "port": 993,
    "encryption": "SSL",
    "userName": "imap-username"
  }
}

Responses

{
  "emailAccountId": "12345",
  "fromEmail": "john@yourcompany.com",
  "fromName": "John Doe",
  "type": "gmail",
  "status": "active"
}

POSThttps://app.inboxwarm.ai/api/v1/email-accounts/bulk-connect

Connect up to 20 accounts in one call. Each entry is validated and connected independently — one bad or duplicate account doesn't stop the others — and the response reports success or failure per account, in the same order as the input.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccounts": [
    {
      "fromEmail": "john@yourcompany.com",
      "fromName": "John Doe",
      "type": "gmail",
      "smtp": { "host": "smtp.example.com", "port": 587, "password": "your-password", "encryption": "TLS", "userName": "smtp-username" },
      "imap": { "host": "imap.example.com", "port": 993, "encryption": "SSL", "userName": "imap-username" }
    },
    {
      "fromEmail": "sales@yourcompany.com",
      "type": "microsoft",
      "smtp": { "password": "app-specific-password" }
    }
  ]
}

Responses

{
  "results": [
    {
      "success": true,
      "emailAccountId": "12345",
      "fromEmail": "john@yourcompany.com",
      "fromName": "John Doe",
      "type": "gmail",
      "status": "active"
    },
    {
      "success": false,
      "fromEmail": "sales@yourcompany.com",
      "error_code": "already_connected",
      "message": "This email address is already connected.",
      "details": {}
    }
  ]
}

POSThttps://app.inboxwarm.ai/api/v1/email-accounts/{emailAccountId}/disconnect

Pause an account without deleting it. Config and history are preserved for reconnecting later.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}"
}

Responses

{
  "emailAccountId": "12345",
  "status": "disconnected"
}

DELETEhttps://app.inboxwarm.ai/api/v1/email-accounts/{emailAccountId}

Permanently remove an account and all associated warmup data and history.

Auth:query parameterapi_key

Responses

No response body

POSThttps://app.inboxwarm.ai/api/v1/email-accounts/bulk-delete

Permanently remove up to 20 accounts in one call.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountIds": [
    "12345",
    "12346"
  ]
}

Responses

{
  "results": [
    {
      "emailAccountId": "12345",
      "deleted": true
    },
    {
      "emailAccountId": "12346",
      "deleted": true
    }
  ]
}

GEThttps://app.inboxwarm.ai/api/v1/email-accounts/{emailAccountId}/status

Detailed status for a single account — connection health, warmup state, auth status, active errors.

Auth:query parameterapi_key

Responses

{
  "emailAccountId": "12345",
  "fromEmail": "john@yourcompany.com",
  "type": "gmail",
  "authStatus": "connected",
  "warmupStatus": "active",
  "healthScore": 92,
  "connectionError": null,
  "lastConnectedAt": "2026-07-15T08:00:00.000Z"
}

POSThttps://app.inboxwarm.ai/api/v1/email-accounts/bulk-status

Status for up to 50 accounts in one call, returned in the same order as the input IDs.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountIds": [
    "12345",
    "12346"
  ]
}

Responses

{
  "results": [
    {
      "emailAccountId": "12345",
      "fromEmail": "john@yourcompany.com",
      "type": "gmail",
      "authStatus": "connected",
      "warmupStatus": "active",
      "healthScore": 92,
      "connectionError": null,
      "lastConnectedAt": "2026-07-15T08:00:00.000Z"
    },
    {
      "emailAccountId": "12346",
      "fromEmail": "sales@yourcompany.com",
      "type": "microsoft",
      "authStatus": "connected",
      "warmupStatus": "paused",
      "healthScore": 81,
      "connectionError": null,
      "lastConnectedAt": "2026-07-14T22:10:00.000Z"
    }
  ]
}

GEThttps://app.inboxwarm.ai/api/v1/warmup-settings/{emailAccountId}

Fetch the current warmup configuration for an account.

Auth:query parameterapi_key

Responses

{
  "emailAccountId": "12345",
  "displayName": "Ada Lovelace",
  "timeZone": "America/New_York",
  "sendingDays": [1, 2, 3, 4, 5],
  "sendingWindowStartTime": "09:00",
  "sendingWindowEndTime": "17:00",
  "warmupLanguage": "en",
  "targetIndustry": "saas_software",
  "warmupTopics": ["Referral request", "Case study"]
}

PATCHhttps://app.inboxwarm.ai/api/v1/warmup-settings/{emailAccountId}

Update one or more warmup settings for an account — sender name, timezone, sending schedule, language, industry, or topics. Only the fields you send are changed.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "displayName": "Ada Lovelace",
  "timeZone": "America/New_York",
  "sendingDays": [1, 2, 3, 4, 5],
  "sendingWindowStartTime": "09:00",
  "sendingWindowEndTime": "17:00",
  "warmupLanguage": "en",
  "targetIndustry": "saas_software",
  "warmupTopics": ["Referral request", "Case study"]
}

Responses

{
  "emailAccountId": "12345",
  "displayName": "Ada Lovelace",
  "timeZone": "America/New_York",
  "sendingDays": [1, 2, 3, 4, 5],
  "sendingWindowStartTime": "09:00",
  "sendingWindowEndTime": "17:00",
  "warmupLanguage": "en",
  "targetIndustry": "saas_software",
  "warmupTopics": ["Referral request", "Case study"]
}

GEThttps://app.inboxwarm.ai/api/v1/warmup-settings/languages

List every language warmup content can be generated in, so you know which values warmupLanguage accepts.

Auth:query parameterapi_key

Responses

{
  "languages": [
    { "code": "en", "name": "English", "nativeName": "English", "script": "Latin" },
    { "code": "es", "name": "Spanish", "nativeName": "Español", "script": "Latin" },
    { "code": "ja", "name": "Japanese", "nativeName": "日本語", "script": "Japanese" }
  ]
}

GEThttps://app.inboxwarm.ai/api/v1/warmup-settings/industries

List every target industry and its suggested topics, so you know which values targetIndustry and warmupTopics accept.

Auth:query parameterapi_key

Responses

{
  "industries": [
    {
      "key": "e_commerce",
      "name": "E-Commerce",
      "topics": [
        "Abandoned cart follow-up",
        "New product launch",
        "Seasonal sale announcement",
        "Order and shipping update",
        "Customer review request"
      ]
    },
    {
      "key": "saas_software",
      "name": "SaaS / Software",
      "topics": ["Feature announcement", "Onboarding tip", "Case study"]
    }
  ]
}

POSThttps://app.inboxwarm.ai/api/v1/warmup-settings/{emailAccountId}/start

Start warmup for an account.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}"
}

Responses

{
  "emailAccountId": "12345",
  "warmupStatus": "active"
}

POSThttps://app.inboxwarm.ai/api/v1/warmup-settings/{emailAccountId}/stop

Stop warmup for an account.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}"
}

Responses

{
  "emailAccountId": "12345",
  "warmupStatus": "paused"
}

POSThttps://app.inboxwarm.ai/api/v1/warmup-settings/bulk-action

Start or stop warmup for up to 50 accounts in one call.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountIds": [
    "12345",
    "12346"
  ],
  "action": "start"
}

Responses

{
  "results": [
    {
      "emailAccountId": "12345",
      "status": "ok"
    },
    {
      "emailAccountId": "12346",
      "status": "ok"
    }
  ]
}

POSThttps://app.inboxwarm.ai/api/v1/warmup-settings/bulk-update

Apply schedule and/or content settings to up to 50 accounts in one call.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountIds": [
    "12345",
    "12346"
  ],
  "apply": ["language", "window"],
  "warmupLanguage": "es",
  "sendingWindowStartTime": "06:00",
  "sendingWindowEndTime": "10:00"
}

Responses

{
  "updatedCount": 2
}

GEThttps://app.inboxwarm.ai/api/v1/warmup-status/{emailAccountId}

Today's warmup activity for an account: sent, received, replied, spam, bounced.

Auth:query parameterapi_key

Responses

{
  "emailAccountId": "12345",
  "date": "2026-07-15",
  "current": "active",
  "dailySendingLimit": 10,
  "sent": 12,
  "received": 10,
  "replied": 7,
  "spam": 1,
  "bounced": 0
}

GEThttps://app.inboxwarm.ai/api/v1/setup-score/{emailAccountId}

Cached setup health score (DMARC, SPF, DKIM, MX, blacklist checks) for an account.

Auth:query parameterapi_key

Responses

{
  "emailAccountId": "12345",
  "emailAccountScore": 86,
  "dmarcScore": 15,
  "spfScore": 29,
  "dkimScore": 18,
  "mxRecordScore": 9,
  "ipBlacklistScore": 5,
  "domainBlacklistScore": 10,
  "updatedAt": "2026-07-14T10:30:00.000Z",
  "manualLastRefreshedAt": "2026-07-14T10:30:00.000Z"
}

POSThttps://app.inboxwarm.ai/api/v1/setup-score/{emailAccountId}/refresh

Synchronously recompute the setup score for an account.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}"
}

Responses

{
  "emailAccountId": "12345",
  "emailAccountScore": 88,
  "dmarcScore": 15,
  "spfScore": 29,
  "dkimScore": 18,
  "mxRecordScore": 9,
  "ipBlacklistScore": 7,
  "domainBlacklistScore": 10,
  "updatedAt": "2026-07-15T09:00:00.000Z",
  "manualLastRefreshedAt": "2026-07-15T09:00:00.000Z"
}

GEThttps://app.inboxwarm.ai/api/v1/dns-health/{emailAccountId}

Live DNS lookup for the account's sending domain — pass/fail for SPF, DKIM, DMARC, MX.

Auth:query parameterapi_key

Responses

{
  "emailAccountId": "12345",
  "spf": "pass",
  "dkim": "pass",
  "dmarc": "pass",
  "mx": "pass",
  "cachedAt": "2026-07-15T09:00:00.000Z"
}

POSThttps://app.inboxwarm.ai/api/v1/deliverability-score/{emailAccountId}

Overall and per-ESP inbox-vs-spam deliverability rate for a date range.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "startDate": "2026-06-01",
  "endDate": "2026-06-30",
  "esps": [
    "gmail",
    "outlook",
    "other"
  ]
}

Responses

{
  "emailAccountId": "12345",
  "totalDeliverabilityRate": 88,
  "totalSentCount": 1500,
  "totalInboxCount": 1320,
  "totalSpamInboxCount": 180,
  "gmail": {
    "deliverabilityRate": 92,
    "sentCount": 500,
    "inboxCount": 460,
    "spamCount": 40
  },
  "outlook": {
    "deliverabilityRate": 92,
    "sentCount": 500,
    "inboxCount": 460,
    "spamCount": 40
  },
  "other": {
    "deliverabilityRate": 92,
    "sentCount": 500,
    "inboxCount": 460,
    "spamCount": 40
  }
}

GEThttps://app.inboxwarm.ai/api/v1/dashboard

Account-wide warmup summary across all connected inboxes.

Auth:query parameterapi_key

Responses

{
  "totalAccounts": 42,
  "activeWarmups": 30,
  "pausedWarmups": 8,
  "accountsWithErrors": 2,
  "avgSetupScore": 78.5
}

POSThttps://app.inboxwarm.ai/api/v1/reports

Daily warmup report for one account over a date range.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountId": "12345",
  "from": "2026-06-01",
  "to": "2026-06-30"
}

Responses

{
  "emailAccountId": "12345",
  "from": "2026-06-01",
  "to": "2026-06-30",
  "days": [
    {
      "date": "2026-06-15",
      "sent": 25,
      "inbox": 20,
      "received": 22,
      "spam": 3,
      "bounced": 1,
      "undelivered": 0,
      "replied": 5,
      "deliverabilityRate": 92.5
    }
  ]
}

POSThttps://app.inboxwarm.ai/api/v1/reports/bulk

Daily warmup reports for up to 50 accounts over a date range.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountIds": [
    "12345",
    "12346"
  ],
  "from": "2026-06-01",
  "to": "2026-06-30"
}

Responses

{
  "reports": [
    {
      "emailAccountId": "12345",
      "from": "2026-06-01",
      "to": "2026-06-30",
      "days": [
        {
          "date": "2026-06-15",
          "sent": 25,
          "inbox": 20,
          "received": 22,
          "spam": 3,
          "bounced": 1,
          "undelivered": 0,
          "replied": 5,
          "deliverabilityRate": 92.5
        }
      ]
    }
  ]
}

POSThttps://app.inboxwarm.ai/api/v1/reports/export

Kick off an async CSV export of warmup reports, delivered by email when ready.

Auth:body fieldapiKey

Request body

{
  "apiKey": "{{apiKey}}",
  "emailAccountIds": [
    "12345",
    "12346"
  ],
  "from": "2026-06-01",
  "to": "2026-06-30"
}

Responses

{
  "jobId": "a1b2c3d4",
  "status": "queued"
}

InboxWarm API documentation

Base URL#

Authentication#

Rate limits#

Errors#

Endpoint index#

System

Health Check#

Rate Limit Status#

Email Accounts

List Email Accounts#

Connect Email Account#

Bulk Connect Email Accounts#

Disconnect Email Account#

Delete Email Account#

Bulk Delete Email Accounts#

Get Email Account Status#

Bulk Email Account Status#

Warmup

Get Warmup Settings#

Update Warmup Settings#

List Warmup Languages#

List Warmup Industries#

Start Warmup#

Stop Warmup#

Bulk Warmup Action#

Bulk Update Warmup Settings#

Warmup Activity History#

Deliverability

Get Setup Score#

Refresh Setup Score#

DNS Health Check#

Get Deliverability Score#

Reports

Dashboard#

Single Account Report#

Bulk Report#

Export Report#