Authentication

All API requests require an API key passed in the Authorization header.

API keys are created from your dashboard. Each key is tied to your account and shares its scan quota.

Authorization: Bearer sa_live_your_api_key_here

Rate limits

When a limit is exceeded, the API returns 429 Too Many Requests.

Errors

Errors return a JSON body with a detail field:

{ "detail": "Invalid API key" }

Create a new email scan. Returns a unique email address to send your test email to.

The request body can be empty ({}).

Example

curl -X POST https://senderaudit.com/api/v1/scans \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201 Created

{
  "local_part": "s1a2b3c4",
  "email_address": "s1a2b3c4@senderaudit.com",
  "status": "pending",
  "created_at": "2026-03-25T14:32:00",
  "view_count": 0
}

Check the status of a scan. Poll this endpoint until status is completed or failed.

Path parameters

Example

curl https://senderaudit.com/api/v1/scans/s1a2b3c4 \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "local_part": "s1a2b3c4",
  "email_address": "s1a2b3c4@senderaudit.com",
  "status": "completed",
  "created_at": "2026-03-25T14:32:00",
  "received_at": "2026-03-25T14:32:12",
  "processed_at": "2026-03-25T14:32:45",
  "processing_time_ms": 33000,
  "view_count": 0
}

Status values

Retrieve the full analysis results for a completed scan.

Example

curl https://senderaudit.com/api/v1/scans/s1a2b3c4/results \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

Returns 202 Accepted if analysis is still in progress.

Download a ZIP archive containing WebP-optimized versions of all images found in the email. Available only for a limited time after analysis.

Path parameters

Example

curl -OJ https://senderaudit.com/api/v1/scans/s1a2b3c4/optimized-images \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

Returns a binary application/zip file containing optimized images in WebP format.

The Content-Disposition header provides the suggested filename: senderaudit-{local_part}-optimized.zip

Retrieve the authenticated user's profile.

Example

curl https://senderaudit.com/api/v1/auth/me \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "id": 1,
  "email": "user@example.com",
  "is_verified": true,
  "active_account_id": 1,
  "memberships": [
    { "account_id": 1, "role": "owner" }
  ],
  "created_at": "2026-01-15T10:00:00"
}

Check your daily scan quota and current usage.

Example

curl https://senderaudit.com/api/v1/auth/me/scan-usage \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "scans_used_today": 3,
  "scans_limit": 20,
  "scans_remaining": 17
}

List all scans for your account with pagination and optional domain filtering.

Query parameters

Example

curl "https://senderaudit.com/api/v1/auth/me/scans?limit=10&offset=0" \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "scans": [
    {
      "email_address": "s1a2b3c4@senderaudit.com",
      "status": "completed",
      "overall_score": 87,
      "from_header": "noreply@example.com",
      "subject": "Welcome!",
      "spam_score": 1.2,
      "created_at": "2026-03-25T14:32:00",
      "processed_at": "2026-03-25T14:32:45"
    }
  ],
  "total": 42
}

API keys

Manage API keys for your account. Maximum 5 keys per account.

{ "name": "My integration" }

{
  "id": 1,
  "name": "My integration",
  "key": "sa_live_abc123...",
  "key_hint": "c123",
  "created_at": "2026-03-25T14:00:00"
}

{
  "keys": [
    {
      "id": 1,
      "name": "My integration",
      "key_hint": "c123",
      "is_active": true,
      "created_at": "2026-03-25T14:00:00",
      "last_used_at": "2026-04-05T09:15:00"
    }
  ]
}

{ "deleted": true }

Seed addresses

Seed addresses are persistent scan addresses that can receive multiple test emails over time, making it easy to track improvements.

{ "name": "Production newsletter" }

{
  "id": 1,
  "name": "Production newsletter",
  "email": "seed-x7k9m2@senderaudit.com",
  "created_at": "2026-03-25T14:00:00"
}

{
  "addresses": [
    {
      "id": 1,
      "name": "Production newsletter",
      "email": "seed-x7k9m2@senderaudit.com",
      "is_active": true,
      "created_at": "2026-03-25T14:00:00",
      "last_used_at": "2026-04-01T08:30:00"
    }
  ],
  "limit": 10
}

{ "deleted": true }

List all domains registered on your account.

Example

curl https://senderaudit.com/api/v1/domains \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

[
  {
    "id": "a1b2c3d4-...",
    "domain": "example.com",
    "verification_method": "dns",
    "is_verified": true,
    "verified_at": "2026-03-20T10:00:00",
    "created_at": "2026-03-20T09:50:00",
    "monitored_hosts_count": 3
  }
]

Start domain ownership verification. Choose between DNS (TXT record) or email-based verification.

Request body

Example

curl -X POST https://senderaudit.com/api/v1/domains/initiate \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com", "method": "dns" }'

Response 201 Created

{
  "id": "a1b2c3d4-...",
  "domain": "example.com",
  "verification_method": "dns",
  "verification_token": "senderaudit_verify:abc123def456",
  "is_verified": false,
  "created_at": "2026-03-25T14:00:00",
  "monitored_hosts_count": 0
}

Attempt to verify domain ownership. For DNS verification, checks that the TXT record is present.

Path parameters

Example

curl -X POST https://senderaudit.com/api/v1/domains/a1b2c3d4-.../verify \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "status": "verified"
}

Remove a domain and all its associated monitoring data.

Example

curl -X DELETE https://senderaudit.com/api/v1/domains/a1b2c3d4-... \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 204 No Content

Empty response body.

Check your domain and monitored hosts quota.

Example

curl https://senderaudit.com/api/v1/domains/quota \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "plan": "pro",
  "monitored_hosts_used": 5,
  "monitored_hosts_total": 8,
  "monitored_hosts_limit": 20
}

Retrieve current DNS records and change timeline for a verified domain.

Path parameters

Example

curl https://senderaudit.com/api/v1/domains/a1b2c3d4-.../monitoring \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "records": [
    {
      "id": 1,
      "record_type": "SPF",
      "record_key": "example.com",
      "record_value": "v=spf1 include:_spf.google.com ~all",
      "first_seen_at": "2026-03-20T10:00:00",
      "last_seen_at": "2026-04-05T06:00:00",
      "removed_at": null
    }
  ],
  "timeline": [
    {
      "record_type": "DMARC",
      "record_key": "_dmarc.example.com",
      "record_value": "v=DMARC1; p=reject;",
      "first_seen_at": "2026-03-22T10:00:00",
      "removed_at": "2026-04-01T06:00:00"
    }
  ],
  "building": false
}

List all monitored hosts (IPs, domains) discovered from scan results for this domain.

Example

curl https://senderaudit.com/api/v1/domains/a1b2c3d4-.../monitored-items \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "hosts": [
    {
      "id": 1,
      "host_value": "example.com",
      "is_active": true,
      "types": [
        { "host_type": "header_from", "discovered_by": "scan" }
      ],
      "created_at": "2026-03-20T10:00:00"
    },
    {
      "id": 2,
      "host_value": "198.51.100.25",
      "is_active": true,
      "types": [
        { "host_type": "sending_ip", "discovered_by": "scan" }
      ],
      "created_at": "2026-03-20T10:00:00"
    }
  ]
}

Toggle the active state of a monitored host. Deactivated hosts stop being monitored and free up quota.

Path parameters

Example

curl -X PATCH https://senderaudit.com/api/v1/domains/a1b2c3d4-.../monitored-items/2 \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "id": 2,
  "is_active": false
}

Get the average deliverability score, percentile ranking, and certificate eligibility for a domain.

Example

curl https://senderaudit.com/api/v1/domains/a1b2c3d4-.../score-summary \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "avg_score": 92,
  "scan_count": 8,
  "percentile": 87,
  "eligible_certificate": true,
  "certificate": {
    "token": "cert_abc123",
    "avg_score": 92,
    "updated_at": "2026-04-05T06:00:00"
  }
}

List all IPs registered on your account.

Example

curl https://senderaudit.com/api/v1/ips \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

[
  {
    "id": "a1b2c3d4-...",
    "ip_value": "51.178.83.230",
    "input_type": "single",
    "ip_count": 1,
    "root_domains": ["example.com"],
    "verification_method": "dns",
    "is_verified": true,
    "verified_at": "2026-04-05T10:00:00",
    "created_at": "2026-04-05T09:50:00"
  }
]

Resolve PTR records for an IP and return available verification targets. Use this before /ips/initiate to preview which hostnames and email addresses are available for verification.

Request body

Example

curl -X POST https://senderaudit.com/api/v1/ips/preview \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ip_value": "51.178.83.230" }'

Response 200 OK

{
  "ip_value": "51.178.83.230",
  "input_type": "single",
  "ip_count": 1,
  "ptr_hostnames": ["mail.example.com"],
  "root_domains": ["example.com"],
  "ptr_map": { "51.178.83.230": "mail.example.com" },
  "is_multi": false,
  "dns_targets": {
    "ptr": ["mail.example.com"],
    "root": ["example.com"]
  },
  "email_targets": {
    "ptr": {
      "postmaster": ["postmaster@mail.example.com"],
      "abuse": ["abuse@mail.example.com"],
      "contact": ["contact@mail.example.com"],
      "support": ["support@mail.example.com"],
      "admin": ["admin@mail.example.com"]
    },
    "root": {
      "postmaster": ["postmaster@example.com"],
      "abuse": ["abuse@example.com"],
      "contact": ["contact@example.com"],
      "support": ["support@example.com"],
      "admin": ["admin@example.com"]
    }
  }
}

Start IP ownership verification. Choose between DNS (TXT record on the PTR hostname) or email-based verification.

Request body

Example

curl -X POST https://senderaudit.com/api/v1/ips/initiate \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ip_value": "51.178.83.230", "method": "dns", "scope": "ptr" }'

Response 201 Created

{
  "id": "a1b2c3d4-...",
  "ip_value": "51.178.83.230",
  "input_type": "single",
  "ip_count": 1,
  "root_domains": ["example.com"],
  "ptr_map": { "51.178.83.230": "mail.example.com" },
  "verification_method": "dns",
  "verification_token": "senderaudit_verify:abc123def456",
  "verification_hosts": ["mail.example.com"],
  "is_verified": false,
  "verified_at": null,
  "created_at": "2026-04-05T09:50:00"
}

Attempt to verify IP ownership via DNS TXT record. Checks that the TXT record is present on each verification host.

Path parameters

Example

curl -X POST https://senderaudit.com/api/v1/ips/a1b2c3d4-.../verify \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "status": "verified"
}

Retrieve the structured health card for a verified IP. Returns a 5-category score breakdown out of 100.

Path parameters

Example

curl https://senderaudit.com/api/v1/ips/a1b2c3d4-.../health-card \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 200 OK

{
  "overall": 85,
  "max": 100,
  "crisis": false,
  "categories": [
    {
      "key": "reputation",
      "label": "Reputation",
      "score": 30,
      "max": 30,
      "items": [
        {
          "key": "rbl",
          "label": "Blocklists (RBL)",
          "status": "pass",
          "score": 30,
          "max": 30,
          "value": "0 / 45 - Clean",
          "summary": "Not listed on any of 45 monitored blocklists",
          "details": { "listings": [...], "crisis": false }
        }
      ]
    },
    { "key": "identity", "label": "Identity", "score": 20, "max": 20, "items": [...] },
    { "key": "connectivity", "label": "Connectivity", "score": 15, "max": 20, "items": [...] },
    { "key": "senderscore", "label": "SenderScore", "score": 16, "max": 20, "items": [...] },
    { "key": "geoip", "label": "GeoIP", "score": 10, "max": 10, "items": [...] }
  ],
  "actions": [
    {
      "category": "connectivity",
      "item": "smtp_banner",
      "label": "SMTP Banner",
      "status": "fail",
      "gain": 10,
      "summary": "No SMTP banner"
    }
  ],
  "sparkline": [80, 82, 85, 85],
  "ip_value": "51.178.83.230",
  "input_type": "single",
  "ip_count": 1,
  "ptr_map": { "51.178.83.230": "mail.example.com" },
  "root_domains": ["example.com"]
}

Remove an IP and all its associated monitoring data (DNS records, health scores).

Example

curl -X DELETE https://senderaudit.com/api/v1/ips/a1b2c3d4-... \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

Response 204 No Content

Empty response body.

Typical flow

Complete example (bash)

#!/bin/bash
API_KEY="sa_live_YOUR_KEY"
BASE="https://senderaudit.com/api/v1"

# 1. Create scan
RESPONSE=$(curl -s -X POST "$BASE/scans" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}')
LOCAL=$(echo "$RESPONSE" | jq -r '.local_part')
EMAIL=$(echo "$RESPONSE" | jq -r '.email_address')

echo "Send your email to: $EMAIL"
echo "Waiting for analysis..."

# 2. Send your email (via your SMTP server)
# echo "Test" | mail -s "Deliverability check" "$EMAIL"

# 3. Poll until completed
while true; do
  STATUS=$(curl -s "$BASE/scans/$LOCAL" \
    -H "Authorization: Bearer $API_KEY" | jq -r '.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Scan failed" && exit 1
  sleep 5
done

# 4. Get results
curl -s "$BASE/scans/$LOCAL/results" \
  -H "Authorization: Bearer $API_KEY" | jq '.scores'