InboxIssue Documentation

The Spam Tests API is the core InboxIssue API for email deliverability testing. Use this API to create tests, send your emails, and view results.

Viewing Results: Spam test results are typically viewed on the shareable reports page in the InboxIssue dashboard. Each test has a unique URL you can share with your team or clients.

Create Spam Test

Create a new spam test with all available providers.

POST /api/v1/spam_tests

Request Body

{
  "spam_test": {
    "name": "Newsletter Campaign Test",
    "sender_email_address": "newsletter@yourcompany.com",
    "provider_types": ["consumer", "business"],
    "metadata": {
      "campaign_id": "camp_123"
    }
  }
}

Parameters

Parameter	Type	Required	Description
`name`	string	No	Human-readable test name
`sender_email_address`	string	No	From address for tracking
`provider_types`	array	No	Provider types to include
`metadata`	object	No	Custom key-value pairs

Response

Returns 201 Created on success with test details and send instructions.

{
  "success": true,
  "spam_test": {
    "id": 12345,
    "public_id": "ABC123",
    "name": "Newsletter Campaign Test",
    "status": "pending",
    "tracking_key": "inboxissue-12345-2024-01-15-inboxissue",
    "created_at": "2024-01-15T10:30:00Z",
    "send_to": [
      "test1@gmail.com",
      "test2@yahoo.com",
      "test3@outlook.com"
    ]
  },
  "instructions": {
    "message": "Send your test email to the addresses listed in send_to",
    "include_tracking_key": true,
    "timeout_minutes": 60
  }
}

Get Spam Test

Retrieve a spam test by ID or public ID.

GET /api/v1/spam_tests/:id

Path Parameters

Parameter	Type	Description
`id`	string	Test ID or public ID (e.g., `ABC123`)

Response

{
  "success": true,
  "spam_test": {
    "id": 12345,
    "public_id": "ABC123",
    "name": "Newsletter Campaign Test",
    "status": "complete",
    "sender_email_address": "newsletter@yourcompany.com",
    "subject": "Your Weekly Newsletter",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:45:00Z",
    "metadata": {
      "campaign_id": "camp_123"
    }
  },
  "summary": {
    "total": 10,
    "inbox": 8,
    "spam": 2,
    "missing": 0,
    "inbox_rate": 80.0
  },
  "results": [
    {
      "id": 98765,
      "email_provider": {
        "name": "gmail.com",
        "type": "consumer"
      },
      "delivery": {
        "status": "delivered",
        "folder": "INBOX",
        "is_inbox": true,
        "is_spam": false,
        "delivery_time_seconds": 165
      },
      "authentication": {
        "spf": { "pass": true, "result": "pass" },
        "dkim": { "pass": true, "result": "pass" },
        "dmarc": { "pass": true, "result": "pass" }
      },
      "received_at": "2024-01-15T10:32:45Z"
    }
  ]
}

List Spam Tests

List spam tests with pagination and filtering.

GET /api/v1/spam_tests

Query Parameters

Parameter	Type	Default	Description
`status`	string	-	Filter: `pending`, `in_progress`, `complete`
`page`	integer	1	Page number
`per_page`	integer	25	Results per page (max 100)

Response

{
  "success": true,
  "spam_tests": [
    {
      "id": 12345,
      "public_id": "ABC123",
      "name": "Newsletter Campaign Test",
      "status": "complete",
      "inbox_rate": 80.0,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 4,
    "total_count": 87
  }
}

Reference

Test Status Values

Status	Description
`pending`	Test created, no results received
`in_progress`	Some results received
`complete`	All results received or test expired

Delivery Status Fields

Field	Type	Description
`status`	string	`delivered`, `pending`, `missing`
`folder`	string	Delivery folder (e.g., `INBOX`, `Junk`)
`is_inbox`	boolean	Delivered to inbox
`is_spam`	boolean	Delivered to spam/junk
`delivery_time_seconds`	integer	Time from send to receipt

Authentication Results

Each result includes authentication analysis:

Field	Description
`spf`	SPF verification result
`dkim`	DKIM signature verification
`dmarc`	DMARC policy compliance
`comp_auth`	Microsoft composite authentication

Microsoft Spam Scores

Microsoft mailboxes include spam confidence scores:

Score	Range	Description
`microsoft_scl`	0-9	Spam Confidence Level
`microsoft_bcl`	0-9	Bulk Complaint Level

Code Examples

import requests
 
API_TOKEN = "your_api_token"
BASE_URL = "https://app.inboxissue.com/api/v1"
 
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}
 
# Create a test
response = requests.post(
    f"{BASE_URL}/spam_tests",
    headers=headers,
    json={
        "spam_test": {
            "name": "My Campaign Test",
            "provider_types": ["consumer", "business"]
        }
    }
)
test = response.json()
 
print(f"Send emails to: {test['spam_test']['send_to']}")
print(f"Include tracking key: {test['spam_test']['tracking_key']}")
 
# Get results
test_id = test['spam_test']['public_id']
response = requests.get(
    f"{BASE_URL}/spam_tests/{test_id}",
    headers=headers
)
result = response.json()
print(f"Inbox rate: {result['summary']['inbox_rate']}%")

External Tests API

For third-party integrations

Webhooks

Real-time result notifications

Code Examples

Full SDK examples

Spam Tests API

External Tests API

Webhooks

Code Examples

On this page