External Tests API

The External Tests API is designed for third-party integrations like DMARC Reporter, New Reply, and other services that need to embed deliverability testing.

For direct InboxIssue users: Consider using the Spam Tests API instead, which provides richer features and shareable reports.

Webhooks Recommended: External Tests are typically used with webhooks for real-time result notifications. This allows your integration to receive results automatically without polling.

Quick Start

1. Get Available Test Addresses

curl -X GET "https://app.inboxissue.com/api/v1/external_tests/providers" \
  -H "Authorization: Bearer YOUR_TOKEN"

2. Create a Test

curl -X POST "https://app.inboxissue.com/api/v1/external_tests" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_test": {
      "name": "Campaign Deliverability Check",
      "source": "my_app",
      "metadata": {
        "campaign_id": "camp_123"
      }
    },
    "provider_types": ["consumer", "business"]
  }'

3. Send Your Test Email

Send your email to all addresses returned in send_to. Include the tracking_id in your email body or subject line.

4. Poll for Results

curl -X GET "https://app.inboxissue.com/api/v1/external_tests/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoints

List Providers

Retrieve available test email addresses grouped by provider type.

GET /api/v1/external_tests/providers

Query Parameters

Parameter	Type	Required	Description
`provider_types[]`	array	No	Filter by types: `consumer`, `business`, `protected`

Response

{
  "success": true,
  "providers": {
    "consumer": {
      "description": "Consumer email providers (Gmail, Yahoo, AOL, etc.)",
      "emails": [
        {
          "address": "test1@gmail.com",
          "service": "gmail.com",
          "status": "healthy"
        },
        {
          "address": "test2@yahoo.com",
          "service": "yahoo.com",
          "status": "healthy"
        }
      ]
    },
    "business": {
      "description": "Business email providers (Office 365, Google Workspace)",
      "emails": [
        {
          "address": "test@company.onmicrosoft.com",
          "service": "office365.com",
          "status": "healthy"
        }
      ]
    },
    "protected": {
      "description": "Mailboxes behind commercial spam filters (Mimecast, Proofpoint)",
      "emails": [
        {
          "address": "test@mimecast-protected.example.com",
          "service": "mimecast",
          "status": "healthy"
        }
      ]
    }
  }
}

Provider Types

Type	Description	Examples
`consumer`	Free consumer email	Gmail, Yahoo, AOL, Outlook.com, iCloud
`business`	Enterprise email	Office 365, Google Workspace, Exchange
`protected`	Commercial spam filters	Mimecast, Proofpoint, Barracuda

Provider Status

Status	Description
`healthy`	Active and receiving emails
`degraded`	Experiencing delays
`unhealthy`	Temporarily unavailable

Create Test

Create a new deliverability test.

POST /api/v1/external_tests

Request Body

{
  "external_test": {
    "name": "Q4 Newsletter Test",
    "source": "dmarc_reporter",
    "metadata": {
      "campaign_id": "camp_12345",
      "user_email": "user@example.com"
    }
  },
  "provider_types": ["consumer", "business"]
}

Parameters

Parameter	Type	Required	Description
`external_test.name`	string	No	Human-readable test name
`external_test.source`	string	No	Your application identifier
`external_test.metadata`	object	No	Custom key-value pairs
`provider_types`	array	No	Provider types to test (defaults to all)

Response (201 Created)

{
  "success": true,
  "test": {
    "id": 12345,
    "key": "inboxissue-12345-2024-01-15-inboxissue",
    "tracking_id": "inboxissue-12345-2024-01-15-inboxissue",
    "name": "Q4 Newsletter Test",
    "source": "dmarc_reporter",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-15T11:30:00Z"
  },
  "instructions": {
    "embed_tracking_id": "Include the tracking_id in your email body or subject",
    "format_example": "Your email should contain: inboxissue-12345-2024-01-15-inboxissue",
    "timeout_minutes": 60
  },
  "send_to": {
    "consumer": ["test1@gmail.com", "test2@yahoo.com"],
    "business": ["test@company.onmicrosoft.com"]
  }
}

Important: You MUST include the tracking_id in your email body or subject line for InboxIssue to correlate results with your test.

Get Test Status

Retrieve test status and results.

GET /api/v1/external_tests/:id

Path Parameters

Parameter	Type	Description
`id`	integer/string	Test ID or test key

Response

{
  "success": true,
  "test": {
    "id": 12345,
    "key": "inboxissue-12345-2024-01-15-inboxissue",
    "name": "Q4 Newsletter Test",
    "source": "dmarc_reporter",
    "status": "in_progress",
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "campaign_id": "camp_12345"
    }
  },
  "summary": {
    "total_providers": 10,
    "completed": 7,
    "pending": 3,
    "inbox": 5,
    "spam": 2,
    "missing": 0,
    "inbox_rate": 71.4
  },
  "results": [
    {
      "id": 98765,
      "provider_type": "consumer",
      "service": "gmail.com",
      "email": "test1@gmail.com",
      "status": "received",
      "delivered_to": "INBOX",
      "is_inbox": true,
      "is_spam": false,
      "authentication": {
        "spf": "pass",
        "dkim": "pass",
        "dmarc": "pass"
      },
      "spam_scores": {
        "microsoft_scl": 1,
        "microsoft_bcl": 0
      },
      "received_at": "2024-01-15T10:32:45Z"
    }
  ]
}

Test Status Values

Status	Description
`pending`	Test created, no results yet
`in_progress`	Some results received
`complete`	All results received
`expired`	Timed out (60 minutes)

Result Status Values

Status	Description
`pending`	Waiting for email
`received`	Email received and analyzed

List Tests

List external tests with pagination.

GET /api/v1/external_tests

Query Parameters

Parameter	Type	Default	Description
`source`	string	-	Filter by source
`status`	string	-	Filter by status
`page`	integer	1	Page number
`per_page`	integer	10	Results per page (max 50)

Response

{
  "success": true,
  "tests": [
    {
      "id": 12345,
      "key": "inboxissue-12345-2024-01-15-inboxissue",
      "name": "Q4 Newsletter Test",
      "source": "dmarc_reporter",
      "status": "complete",
      "inbox_rate": 85.7,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 5,
    "total_count": 47
  }
}

Result Details

Authentication Results

Each result includes authentication details:

{
  "authentication": {
    "spf": {
      "pass": true,
      "result": "pass",
      "details": "sender IP authorized"
    },
    "dkim": {
      "pass": true,
      "result": "pass",
      "details": "signature verified"
    },
    "dmarc": {
      "pass": true,
      "result": "pass",
      "action": "none"
    },
    "comp_auth": {
      "result": "pass",
      "reason_code": 200
    }
  }
}

Spam Scores

Microsoft providers return detailed spam scores:

{
  "spam_scores": {
    "microsoft_scl": {
      "score": 1,
      "max": 9,
      "interpretation": "Very low spam probability"
    },
    "microsoft_bcl": {
      "score": 0,
      "max": 9,
      "interpretation": "Not bulk mail"
    }
  }
}

See Deliverability Insights for score interpretation.

Best Practices

Use Meaningful Metadata

Include metadata for result correlation:

{
  "metadata": {
    "campaign_id": "camp_123",
    "user_id": "user_456",
    "template_version": "v2"
  }
}

Test All Provider Types

For comprehensive results:

{
  "provider_types": ["consumer", "business", "protected"]
}

Use Webhooks

Instead of polling, use webhooks for real-time results.

Handle Expiration

Tests expire after 60 minutes. Check for expired status:

result = client.get_test(test_id)
if result['test']['status'] == 'expired':
    # Some results may be missing
    pass

Authentication - API tokens
Code Examples - SDK examples
Webhooks - Real-time notifications

External Tests API

On this page