InboxIssue
API Reference

Spam Tests API

Create and retrieve spam test results via API

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 selected providers.

POST /api/v1/spam_tests

Request Body

{
  "spam_test": {
    "name": "Newsletter Campaign Test"
  },
  "provider_types": ["consumer", "business"]
}

Parameters

ParameterTypeRequiredDescription
spam_test.namestringNoHuman-readable test name
provider_typesarrayNoProvider types to include: consumer, business, protected

You can also pass external_test parameters to create an external-style test through this endpoint. See External Tests API for that use case.

Response

{
  "success": true,
  "test": {
    "tracking_id": "ABC123",
    "name": "Newsletter Campaign Test",
    "source": null,
    "metadata": {}
  },
  "instructions": {
    "send_to": {
      "consumer": ["test1@gmail.com", "test2@yahoo.com"],
      "business": ["test@company.onmicrosoft.com"]
    }
  }
}

Response Fields

FieldTypeDescription
test.tracking_idstringPublic ID for the test — use this to retrieve results
test.namestringTest name
test.sourcestringSource identifier (if created as external test)
test.metadataobjectCustom metadata (if provided)
instructions.send_toobjectEmail addresses grouped by provider type — send your test email to all of these

Error Responses

422 — Invalid provider types:

{
  "success": false,
  "error": "Invalid provider types: invalid_type"
}

503 — Email monitoring setup failed:

{
  "success": false,
  "error": "There was an error setting up Spam Test. Please try again or contact support if issue persists."
}

Get Spam Test

Retrieve a spam test by ID, public ID, or key.

GET /api/v1/spam_tests/:id

Path Parameters

ParameterTypeDescription
idstringTest ID, public ID (e.g., ABC123), or tracking key

Response

{
  "success": true,
  "data": {
    "key": "inboxissue-12345-2024-01-15-inboxissue",
    "name": "Newsletter Campaign Test",
    "test_results": [
      {
        "delivered_to": "INBOX",
        "dkim_pass": true,
        "spf_pass": true,
        "dmarc_pass": true,
        "to": "test1@gmail.com",
        "from": "newsletter@yourcompany.com"
      },
      {
        "delivered_to": "Spam",
        "dkim_pass": true,
        "spf_pass": false,
        "dmarc_pass": false,
        "to": "test2@yahoo.com",
        "from": "newsletter@yourcompany.com"
      }
    ]
  }
}

Response Fields

FieldTypeDescription
data.keystringTracking key for the test
data.namestringTest name
data.test_resultsarrayArray of per-provider results
test_results[].delivered_tostringDelivery folder: INBOX, Spam, Promotions, etc. null if not yet received
test_results[].dkim_passbooleanDKIM verification passed
test_results[].spf_passbooleanSPF verification passed
test_results[].dmarc_passbooleanDMARC policy check passed
test_results[].tostringRecipient email address
test_results[].fromstringSender email address

Delivery folders: Gmail results may show INBOX, Spam, Promotions, Social, Updates, or Forums. Microsoft results show INBOX or Spam (mapped from Junk).

Additional Endpoints

List Email Services

Returns available email providers grouped by type.

GET /api/v1/spam_tests/email_services

Response

{
  "consumer": ["test1@gmail.com", "test2@yahoo.com"],
  "business": ["test@company.onmicrosoft.com"],
  "protected": ["test@mimecast-example.com"]
}

Reference

Delivery Folder Values

FolderDescription
INBOXPrimary inbox
SpamSpam or junk folder
PromotionsGmail Promotions tab
SocialGmail Social tab
UpdatesGmail Updates tab
ForumsGmail Forums tab

Authentication Results

Each result includes authentication analysis:

FieldTypeDescription
spf_passbooleanSPF verification result
dkim_passbooleanDKIM signature verification
dmarc_passbooleanDMARC policy compliance

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"Tracking ID: {test['test']['tracking_id']}")
print(f"Send emails to: {test['instructions']['send_to']}")
 
# Get results
tracking_id = test['test']['tracking_id']
response = requests.get(
    f"{BASE_URL}/spam_tests/{tracking_id}",
    headers=headers
)
result = response.json()
 
for tr in result['data']['test_results']:
    print(f"{tr['to']}: {tr['delivered_to']} (SPF: {tr['spf_pass']}, DKIM: {tr['dkim_pass']}, DMARC: {tr['dmarc_pass']})")

External Tests API

For third-party integrations with richer result details

Webhooks

Real-time result notifications

Code Examples

Full SDK examples

Previous

Authentication

Next

External Tests API

On this page