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.

From Header ⚠️

Critical check: Valid sender email required

SpamAssassin

Industry-standard spam filtering with detailed test results

SPF Validation

Sender Policy Framework authentication checking

DKIM Validation

DomainKeys signature verification

DMARC Check

Domain-based authentication policy validation

Quick Start

  1. Create a test by sending a POST request to /api/v1/tests
  2. Send an email to the provided test address
  3. Get results by sending a GET request to /api/v1/tests/{test_id}

Example Workflow

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

# Response:
{
  "success": true,
  "data": {
    "test_id": "abc123...",
    "email_address": "test-abc123...@spamchap.com",
    "sender_email": null,
    "status": "pending",
    "created_at": "2025-11-03T15:00:00+00:00",
    "expires_at": "2025-11-04T15:00:00+00:00"
  }
}

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

# Step 3: Get results (wait a few seconds for processing)
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.

Parameters (optional)
  • sender_email - Optional. The sender email is automatically extracted from the email's From header when processing.
Response
{
  "success": true,
  "data": {
    "test_id": "ef72bbf61f97e29ec07df5934c3c6e64",
    "email_address": "test-ef72bbf61f97e29ec07df5934c3c6e64@spamchap.com",
    "sender_email": null,
    "status": "pending",
    "created_at": "2025-11-03T14:59:42+00:00",
    "expires_at": "2025-11-04T14:59:42+00:00"
  }
}

Note: sender_email will be automatically populated from the From header when the email is processed.

GET /api/v1/tests/{test_id}

Get test results

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

Response
{
  "success": true,
  "data": {
    "test_id": "ef72bbf61f97e29ec07df5934c3c6e64",
    "email_address": "test-ef72bbf61f97e29ec07df5934c3c6e64@spamchap.com",
    "sender_email": "leads@thegrapevine.co.za",
    "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": "From Header",
        "status": "pass",
        "message": "Valid sender email found: leads@thegrapevine.co.za",
        "score_impact": 1.0
      },
      {
        "category": "SpamAssassin",
        "status": "pass",
        "message": "Email passed spam check",
        "score_impact": 5.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. Useful for debugging.

Response
{
  "success": true,
  "data": {
    "test_id": "ef72bbf61f97e29ec07df5934c3c6e64",
    "raw_email": "Received: from mail-sender.example.com...\nFrom: sender@example.com\n..."
  }
}
DELETE /api/v1/tests/{test_id}

Delete a test

Permanently deletes a test and all associated data.

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

Scoring System

SpamChap uses a weighted scoring system (0-10 scale, higher is better):

Component Weight Max Points Description
From Header 10% 1.0 CRITICAL: Valid From header with sender email
SpamAssassin 50% 5.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
Other Headers 5% 0.5 Required headers (To, Subject, Date, Message-ID)

Score Interpretation

9.0 - 10.0: Excellent 7.0 - 8.9: Good 0.0 - 6.9: Needs Improvement

⚠️ Critical: Emails without a valid From header will be rejected by most mail servers. This is a required header per RFC 5322 email standards. If your email fails this check, it will not be deliverable.

Error Responses

All errors return appropriate HTTP status codes with a JSON error response:

{
  "name": "Not Found",
  "message": "Test not found",
  "code": 0,
  "status": 404,
  "type": "yii\\web\\NotFoundHttpException"
}
Common Status Codes
  • 200 OK - Request successful
  • 201 Created - Test created successfully
  • 404 Not Found - Test not found or expired
  • 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)
  • Raw emails are stored but may be deleted after processing