Unspam API Usage Examples

All examples use curl  . Replace YOUR_API_TOKEN   with your actual API token found on the Subscription page under API Token.

Discover more information about API Endpoints here.

Every request must include the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Account

Get Account Status

curl --location "https://api.unspam.email/ext/v2/status" \
--header "Authorization: Bearer YOUR_API_TOKEN"

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

curl --location "https://api.unspam.email/ext/v2/inbox-placement/mailboxes" \
--header "Authorization: Bearer YOUR_API_TOKEN"

Response:

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

Start New Inbox Placement Test

Using all available mailboxes:

curl --location --request POST "https://api.unspam.email/ext/v2/inbox-placement" \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json"

Using specific mailboxes only:

curl --location --request POST "https://api.unspam.email/ext/v2/inbox-placement" \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "mailboxes": [3, 7, 23]
}'

Response:

{
  "id": "abc123",
  "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 (abc123 ) somewhere in the email body so the system can match your email to the test.

Example email:
To: test-xyz@gmail.com, test-xyz@outlook.com
Subject: Your March Newsletter
Body:

Hi there,

Check out our latest

abc123

List Inbox Placement Tests

curl --location "https://api.unspam.email/ext/v2/inbox-placement?page=1&per_page=15" \
--header "Authorization: Bearer YOUR_API_TOKEN"

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": "abc123",
      "status": "completed",
      "started_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:35:00Z",
      "report_url": "https://app.unspam.email/inbox-placement/abc123"
    }
  ]
}

Get Inbox Placement Test Result

curl --location "https://api.unspam.email/ext/v2/inbox-placement/abc123" \
--header "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "id": "abc123",
  "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/abc123"
}

Spam Check

Start New Spam Check Test

curl --location --request POST "https://api.unspam.email/ext/v2/spam-check" \
--header "Authorization: Bearer YOUR_API_TOKEN"

Response:

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

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

List Spam Check Tests

curl --location "https://api.unspam.email/ext/v2/spam-check?page=1&per_page=15" \
--header "Authorization: Bearer YOUR_API_TOKEN"

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

Get Spam Check Test Result

curl --location "https://api.unspam.email/ext/v2/spam-check/def456" \
--header "Authorization: Bearer YOUR_API_TOKEN"

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

Screenshots are available after the test is completed.

curl --location "https://api.unspam.email/ext/v2/spam-check/def456/screenshots" \
--header "Authorization: Bearer YOUR_API_TOKEN"

Response:

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

Get Heatmap

Heatmaps may take additional time to generate after a test completes. If the response contains "processing"   values, wait a few seconds and retry.

curl --location "https://api.unspam.email/ext/v2/spam-check/def456/heatmap" \
--header "Authorization: Bearer YOUR_API_TOKEN"

Response (still processing):

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

Response (completed):

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

Full Workflow Examples

Inbox Placement: End-to-End

# 1. (Optional) Check which mailboxes are available
curl --location "https://api.unspam.email/ext/v2/inbox-placement/mailboxes" \
--header "Authorization: Bearer YOUR_API_TOKEN"

# 2. Start a new test
curl --location --request POST "https://api.unspam.email/ext/v2/inbox-placement" \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json"

# Response: { "id": "abc123", "mailboxes": [...] }

# 3. Send your email to each mailbox address from the response.
#    Include "abc123" in the email body.

# 4. Wait a few minutes, then check the result
curl --location "https://api.unspam.email/ext/v2/inbox-placement/abc123" \
--header "Authorization: Bearer YOUR_API_TOKEN"

Spam Check: End-to-End

# 1. Start a new test
curl --location --request POST "https://api.unspam.email/ext/v2/spam-check" \
--header "Authorization: Bearer YOUR_API_TOKEN"

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

# 2. Send your email to test-xyz@check.unspam.email

# 3. Wait a few minutes, then check the result
curl --location "https://api.unspam.email/ext/v2/spam-check/def456" \
--header "Authorization: Bearer YOUR_API_TOKEN"

# 4. (Optional) Get screenshots
curl --location "https://api.unspam.email/ext/v2/spam-check/def456/screenshots" \
--header "Authorization: Bearer YOUR_API_TOKEN"

# 5. (Optional) Get heatmaps
curl --location "https://api.unspam.email/ext/v2/spam-check/def456/heatmap" \
--header "Authorization: Bearer YOUR_API_TOKEN"
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us