Unspam API Endpoints

The Unspam platform can be accessed via API. API access is available exclusively on specific subscription plans. Please ensure your current plan supports API usage before integrating. Find additional information about API Usage Examples here.

Base URL

All API requests should be made to:

https://api.unspam.email/ext/v2

Authentication

All requests require a Bearer token. You can find your API token on the Subscription page under API Token. Include it in every request as a header:

Authorization: Bearer YOUR_API_TOKEN

Make sure your API token is securely stored and never exposed in client-side code.

Response Codes

Rate Limits

All API endpoints are rate-limited to 100 requests per minute per IP address. Authenticated requests are rate-limited per user account instead. Exceeding the limit will result in a 429 Too Many Requests   response.

Account

Get Account Status

Returns your current email and subscription details including plan limits.

GET /status

Response:

{
  "email": "user@example.com",
  "subscription": {
    "name": "White Label",
    "limits": {
      "spam_check": 500,
      "inbox_placement": 100,
      "screenshots": 500,
      "heatmaps": 500,
      "has_history": true,
      "has_ai_assistant": true
    }
  }
}

Inbox Placement

List Available Mailboxes

Returns all enabled mailboxes that can be used for inbox placement tests.

GET /inbox-placement/mailboxes

Response:

[
  {
    "id": 1,
    "name": "Gmail",
    "address": "test-xyz@gmail.com"
  },
  {
    "id": 2,
    "name": "Outlook",
    "address": "test-xyz@outlook.com"
  }
]

List Inbox Placement Tests

Returns a paginated list of inbox placement tests created via API.

GET /inbox-placement

Parameters:

Response:

{
  "current_page": 1,
  "last_page": 3,
  "per_page": 15,
  "total": 42,
  "first_page_url": "...",
  "last_page_url": "...",
  "next_page_url": "...",
  "prev_page_url": null,
  "data": [
    {
      "id": "14838:2026-02-11-10:42:53:000000811",
      "status": "completed",
      "started_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:35:00Z",
      "report_url": "https://app.unspam.email/inbox-placement/14838:2026-02-11-10:42:53:000000811"
    }
  ]
}

Start New Inbox Placement Test

Creates a new inbox placement test. Optionally filter which mailboxes to use.

POST /inbox-placement

Request body (optional):

{
  "mailboxes": [3, 7, 23]
}

If mailboxes   is omitted, all enabled mailboxes are used.

Response (201):

{
  "id": "14838:2026-02-11-10:42:53:000000811",
  "mailboxes": [
    {
      "id": 3,
      "name": "Gmail",
      "address": "test-xyz@gmail.com"
    },
    {
      "id": 7,
      "name": "Outlook",
      "address": "test-xyz@outlook.com"
    }
  ]
}

After receiving the response, send your email to each mailbox address. Include the test ID in the email body so the system can match it.

Example email:

Get Inbox Placement Test Result

Returns the inbox placement test result with per-mailbox delivery status.

GET /inbox-placement/{id}

Parameters:

Response:

{
  "id": "14838:2026-02-11-10:42:53:000000811",
  "status": "completed",
  "started_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:00Z",
  "results": [
    {
      "mailbox": {
        "id": 3,
        "name": "Gmail",
        "address": "test-xyz@gmail.com"
      },
      "status": "delivered",
      "tab": "inbox",
      "sender": "sender@yourdomain.com",
      "sender_ip": "192.0.2.1",
      "blacklists": 0
    }
  ],
  "report_url": "https://app.unspam.email/inbox-placement/14838:2026-02-11-10:42:53:000000811"
}

Spam Check

List Spam Check Tests

Returns a paginated list of spam check tests created via API.

GET /spam-check

Parameters:

Response:

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 5,
  "first_page_url": "...",
  "last_page_url": "...",
  "next_page_url": null,
  "prev_page_url": null,
  "data": [
    {
      "id": "def456",
      "status": "completed",
      "score": 8.5,
      "created_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:33:00Z",
      "report_url": "https://app.unspam.email/result/def456"
    }
  ]
}

Start New Spam Check Test

Creates a new spam check test.

POST /spam-check

Response (201):

{
  "id": "def456",
  "inbox_address": "test-xyz@check.unspam.email"
}

After receiving the response, send your email to the inbox_address  .

Get Spam Check Test Result

Returns the spam check test result with detailed check results.

GET /spam-check/{id}

Parameters:

Response:

{
  "id": "def456",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:33:00Z",
  "sender_host": "yourdomain.com",
  "sender": "sender@yourdomain.com",
  "sender_ip": "192.0.2.1",
  "score": 8.5,
  "message_id": "<abc@yourdomain.com>",
  "results": [
    {
      "id": "spf_check",
      "name": "SPF Check",
      "test_info": "Verifies SPF record configuration",
      "data": {}
    }
  ],
  "report_url": "https://app.unspam.email/result/def456"
}

Get Screenshots

Returns email screenshots rendered on desktop, tablet, and mobile. The test must be completed before screenshots are available.

GET /spam-check/{id}/screenshots

Parameters:

Response:

{
  "desktop": "https://cdn.unspam.email/screenshots/abc-desktop.png",
  "tablet": "https://cdn.unspam.email/screenshots/abc-tablet.png",
  "mobile": "https://cdn.unspam.email/screenshots/abc-mobile.png"
}

Get Heatmap

Returns AI-generated attention and focus heatmap image URLs for desktop, tablet, and mobile. Heatmaps may take additional time to generate after a test completes.

GET /spam-check/{id}/heatmap

Parameters:

Response (processing):

{
  "desktop": "processing",
  "mobile": "processing",
  "tablet": "processing"
}

Response (completed):

{
  "focus": {
    "desktop": "https://cdn.unspam.email/heatmaps/abc-focus-desktop.png",
    "mobile": "https://cdn.unspam.email/heatmaps/abc-focus-mobile.png",
    "tablet": "https://cdn.unspam.email/heatmaps/abc-focus-tablet.png"
  },
  "attention": {
    "desktop": "https://cdn.unspam.email/heatmaps/abc-attention-desktop.png",
    "mobile": "https://cdn.unspam.email/heatmaps/abc-attention-mobile.png",
    "tablet": "https://cdn.unspam.email/heatmaps/abc-attention-tablet.png"
  }
}

If the response contains "processing"   values, wait a few seconds and retry the request.

Flows

Inbox Placement Test Flow

1. (Optional) Fetch the list of available mailboxes via GET /inbox-placement/mailboxes   to select specific ones for your test.
2. Start a new test via POST /inbox-placement  . You can pass specific mailbox IDs in the request body, or omit the parameter to use all available mailboxes. The response contains the test ID and the list of mailboxes used.
3. Send your email to each mailbox address returned in step 2. Include the test ID somewhere in the email body.
4. Wait a few minutes for the system to process the results.
5. Check the result via GET /inbox-placement/{id}   using the test ID from step 2.

Spam Check Test Flow

1. Start a new test via POST /spam-check  . The response contains the test ID and an inbox_address  .
2. Send your email to the inbox_address  .
3. Wait a few minutes for the system to analyze the email.
4. Check the results via GET /spam-check/{id}   using the test ID from step 1.
5. (Optional) Retrieve screenshots via GET /spam-check/{id}/screenshots  .
6. (Optional) Retrieve heatmaps via GET /spam-check/{id}/heatmap  .