Limited Time: Sign up to get your special offer
InboxWarm.ai LogoInboxWarm
Back to API overview

InboxWarm API documentation

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

On this page
Base URLAuthenticationRate limitsErrorsEndpoint index

System

GETHealth CheckGETRate Limit Status

Email Accounts

GETList Email AccountsPOSTConnect Email AccountPOSTBulk Connect Email AccountsPOSTDisconnect Email AccountDELETEDelete Email AccountPOSTBulk Delete Email AccountsGETGet Email Account StatusPOSTBulk Email Account Status

Warmup

GETGet Warmup SettingsPATCHUpdate Warmup SettingsGETList Warmup LanguagesGETList Warmup IndustriesPOSTStart WarmupPOSTStop WarmupPOSTBulk Warmup ActionPOSTBulk Update Warmup SettingsGETWarmup Activity History

Deliverability

GETGet Setup ScorePOSTRefresh Setup ScoreGETDNS Health CheckPOSTGet Deliverability Score

Reports

GETDashboardPOSTSingle Account ReportPOSTBulk ReportPOSTExport Report

Spam Test

POSTStart Spam TestGETGet Spam Test ResultsGETList Spam Tests

Base URL#

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

Authentication#

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",
  ...
}

Rate limits#

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#

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

Endpoint index#

System

Health Check#

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

Basic liveness check for the API.

Auth:query parameterapi_key

Responses

{
  "status": "ok"
}

Rate Limit Status#

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
}

Email Accounts

List Email Accounts#

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
}

Connect Email Account#

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

Bulk Connect Email Accounts#

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

Disconnect Email Account#

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

Delete Email Account#

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

Bulk Delete Email Accounts#

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

Get Email Account Status#

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

Bulk Email Account Status#

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

Warmup

Get Warmup Settings#

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

Update Warmup Settings#

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

List Warmup Languages#

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

List Warmup Industries#

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

Start Warmup#

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

Stop Warmup#

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

Bulk Warmup Action#

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

Bulk Update Warmup Settings#

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
}

Warmup Activity History#

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
}

Deliverability

Get Setup Score#

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

Refresh Setup Score#

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

DNS Health Check#

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

Get Deliverability Score#

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

Reports

Dashboard#

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
}

Single Account Report#

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

Bulk Report#

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

Export Report#

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

Spam Test

Start Spam Test#

POSThttps://app.inboxwarm.ai/api/v1/spam-tests

Start an inbox placement test. Returns a testCode and the seed inboxes to mail. Paste the testCode anywhere in your email — subject line or body — and send that email from the mailbox you want measured to every address in testEmails. We then search those mailboxes for the code to see whether it landed in the inbox or in spam. A test expires 24 hours after it is created if the email never arrives.

Auth:body fieldapiKey

Request body

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

Responses

{
  "testCode": "ibxwrm-4f1c9a7b2e8d05c1",
  "testEmails": [
    "seed.one@gmail.com",
    "seed.two@outlook.com",
    "seed.three@yourseeddomain.com"
  ],
  "status": "pending",
  "expiresAt": "2026-08-19T10:00:00Z"
}

Get Spam Test Results#

GEThttps://app.inboxwarm.ai/api/v1/spam-tests/{testCode}/results

Full placement breakdown for a completed test: where the email landed in each seed mailbox, the inbox/spam percentages and the spam score. Returns 202 not_ready while the test is still running, 410 expired if the window closed before the email arrived, and 409 test_failed if the check itself could not run. unreachableCount counts seed mailboxes we could not open — those are excluded from accountsChecked rather than counted against your email.

Auth:query parameterapi_key

Responses

{
  "testCode": "ibxwrm-4f1c9a7b2e8d05c1",
  "status": "completed",
  "spamScore": 80.0,
  "inboxCount": 4,
  "spamCount": 1,
  "notFoundCount": 0,
  "accountsChecked": [
    {
      "emailAccount": "seed.one@gmail.com",
      "placement": "inbox",
      "foundInInbox": true,
      "foundInSpam": false
    },
    {
      "emailAccount": "seed.two@outlook.com",
      "placement": "spam",
      "foundInInbox": false,
      "foundInSpam": true
    }
  ],
  "unreachableCount": 0,
  "placementSummary": {
    "totalChecked": 5,
    "totalAttempted": 5,
    "unreachableCount": 0,
    "inboxPlacement": { "count": 4, "percentage": 80.0 },
    "spamPlacement": { "count": 1, "percentage": 20.0 },
    "notFound": { "count": 0, "percentage": 0 }
  },
  "expiresAt": "2026-08-19T10:00:00Z"
}

List Spam Tests#

GEThttps://app.inboxwarm.ai/api/v1/spam-tests

List your spam tests, newest first, with the same fields as the status endpoint. Paginated with page and limit (default 20, maximum 100).

Auth:query parameterapi_key

Responses

{
  "items": [
    {
      "testCode": "ibxwrm-4f1c9a7b2e8d05c1",
      "status": "completed",
      "spamScore": 80.0,
      "inboxCount": 4,
      "spamCount": 1,
      "notFoundCount": 0,
      "expiresAt": "2026-08-19T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}