Import known-bad addresses

POST/api/v1/email/suppressions

authentication: Secret API key as a bearer token
billing: Free.

Adds up to 10,000 addresses per request to the suppression list — an email provider's bounce export, a hand-kept blocklist. Addresses are normalized first; ones that do not parse are counted as invalid. An address already on the list keeps the verdict stored with it — a verified answer is better to serve than a synthesized one — is counted as already_suppressed, and becomes an import too; that verdict is served for 90 days after the entry was last renewed, then the import answers with reason suppressed, because nothing verifies an import again. Imported entries are honored from day one at no credit cost: list, bulk and monitor runs answer them with reason suppressed and risk_score 100. An import is your decision rather than a verdict, so no lookup clears it — not a single re-verify, not one through your publishable key — and no delivery report does either: it leaves the list only when you remove it. A complaint reported about it later is recorded on the entry (reason complained, still source imported). An import never goes stale, so importing an address again is never needed.

Request body

field	type	description
emailsrequired	string[]	1 to 10,000 addresses; each item at most 254 characters.

Example request

curl -X POST https://spaw.co/api/v1/email/suppressions \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "[email protected]",
    "[email protected]"
  ]
}'

const response = await fetch('https://spaw.co/api/v1/email/suppressions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "emails": [
      "[email protected]",
      "[email protected]"
    ]
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/email/suppressions',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'emails': [
            '[email protected]',
            '[email protected]'
        ]
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/email/suppressions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'emails' => [
            '[email protected]',
            '[email protected]'
        ]
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.add_suppressions([
    '[email protected]',
    '[email protected]'
])

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.addSuppressions([
    '[email protected]',
    '[email protected]'
]);

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->addSuppressions([
    '[email protected]',
    '[email protected]'
]);

This endpoint has no console on its page. It writes to your account. A documentation page can show you the request; making the change is for the dashboard or for a call you make yourself.

Responses

200How many entries were added, already present, or unparseable.

{
    "success": true,
    "data": {
        "added": 2,
        "already_suppressed": 0,
        "invalid": 0
    }
}

401The key is missing, malformed, or revoked.

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

422The request body could not be validated; `error.errors` lists the fields.

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

429Over 5 requests per second for the key. Retry after the limit resets.

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

Error codes

Failures answer { success: false, error: { code, message, request_id } }. Each code has its own page.

markdown version·openapi.json