SpamChap API

Test your email deliverability, spam score, and authentication (SPF, DKIM, DMARC)

Overview

SpamChap is an email deliverability testing service that analyzes your emails for spam characteristics and authentication issues. Send test emails and get detailed reports with scores from 0–10.

Quick Start

Create a test — POST to /api/v1/tests
Send an email to the provided test address
Get results — GET /api/v1/tests/{test_id}

# Step 1: Create a test
$ curl -X POST https://spamchap.com/api/v1/tests

# Step 2: Send your email to test-abc123...@spamchap.com

# Step 3: Get results
$ curl https://spamchap.com/api/v1/tests/abc123...

API Endpoints

POST /api/v1/tests

Create a new email test

Creates a unique test with a dedicated email address. Tests expire after 24 hours.

Show response

{
  "success": true,
  "data": {
    "test_id": "ef72bbf61f97e29ec07df5934c3c6e64",
    "email_address": "test-ef72bbf61f97e29ec07df5934c3c6e64@spamchap.com",
    "status": "pending",
    "created_at": "2025-11-03T14:59:42+00:00",
    "expires_at": "2025-11-04T14:59:42+00:00"
  }
}

GET /api/v1/tests/{test_id}

Get test results

Retrieves the analysis results for a test. Status will be "pending", "processing", "completed", or "failed".

Show response

{
  "success": true,
  "data": {
    "test_id": "ef72bbf61f97e29ec07df5934c3c6e64",
    "email_address": "test-ef72bbf61f97e29ec07df5934c3c6e64@spamchap.com",
    "status": "completed",
    "score": 10.0,
    "created_at": "2025-11-03T14:59:42+00:00",
    "expires_at": "2025-11-04T14:59:42+00:00",
    "results": [
      {"category": "SpamAssassin", "status": "pass", "message": "Email passed spam check", "score_impact": 6.0},
      {"category": "SPF", "status": "pass", "message": "SPF validation passed", "score_impact": 1.5},
      {"category": "DKIM", "status": "pass", "message": "DKIM signature present and well-formed", "score_impact": 1.5},
      {"category": "DMARC", "status": "pass", "message": "DMARC record found", "score_impact": 0.5},
      {"category": "Headers", "status": "pass", "message": "All required headers present", "score_impact": 0.5}
    ],
    "checks": [
      {"check_name": "SpamAssassin", "result": "pass", "details": {"message": "Email passed spam check", "score": -4.9, "required": 5, "tests": ["DKIM_SIGNED", "DKIM_VALID"]}}
    ]
  }
}

GET /api/v1/tests/{test_id}/raw

Get raw email

Retrieves the original raw email that was received. Returns the raw message as text/plain (not JSON) on success; only error responses are JSON.

Show response

Received: from mail-sender.example.com (mail-sender.example.com [203.0.113.10])
    by mx.spamchap.com with ESMTP id 4XyZab12;
    Mon, 03 Nov 2025 14:59:42 +0000 (UTC)
From: sender@example.com
To: test-ef72bbf61f97e29ec07df5934c3c6e64@spamchap.com
Subject: Test message
Date: Mon, 03 Nov 2025 14:59:42 +0000
Message-ID: <a1b2c3@example.com>
Content-Type: text/plain; charset=UTF-8

This is the plain-text body of the received email.

DELETE /api/v1/tests/{test_id}

Delete a test

Permanently deletes a test and all associated data. Only the creator IP can delete.

Show response

{
  "success": true,
  "message": "Test deleted successfully"
}

Scoring System

Weighted scoring system, 0–10 scale (higher is better):

Component	Weight	Max	Description
SpamAssassin	60%	6.0	Spam content analysis with 100+ tests
SPF	15%	1.5	Sender Policy Framework validation
DKIM	15%	1.5	DomainKeys signature verification
DMARC	5%	0.5	Domain authentication policy check
Headers	5%	0.5	Required header presence validation

9.0–10: Excellent 7.0–8.9: Good 0–6.9: Needs Improvement

Error Responses

All errors return JSON with appropriate HTTP status codes:

{
  "success": false,
  "error": "Test not found"
}

Status Codes

200 OK Request successful

201 Created Test created successfully

404 Not Found Test not found or expired

429 Too Many Requests Rate limit exceeded (10/hour per IP)

500 Internal Server Error Server error

Rate Limits & Notes

Tests expire after 24 hours
Maximum email size: 10 MB
Processing typically completes within seconds
No authentication required (public API)
Rate limited to 10 test creations per hour per IP
Delete restricted to the IP that created the test