SpamFactor API documentation

GET/me

Who you are

Your role, what you may do, and the domains you may see.

curl -H "Authorization: Bearer sf_key_..." https://www.spamfactor.com/api/v1/me

{
    "data": {
        "id": 7,
        "email": "you@example.com",
        "role": "reseller",
        "can_manage_users": true,
        "can_manage_domains": true,
        "can_train": true,
        "domains": ["example.com", "example.net"]
    }
}

GET/domains

List your domains

Add ?check_mx=1 to also check the MX records (up to 50 domains).

curl -H "Authorization: Bearer sf_key_..." "https://www.spamfactor.com/api/v1/domains?check_mx=1"

GET/domains/{id}

One domain

With its users and an MX check: ok, partial, other or none.

POST/domains

Add a domain

Resellers always own the domains they add.

curl -X POST https://www.spamfactor.com/api/v1/domains \
  -H "Authorization: Bearer sf_key_..." -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "dest_host": "mail.example.com", "user_ids": [12]}'

PATCH/domains/{id}

Change a domain

The same fields as above, except domain: a domain name cannot be changed. user_ids replaces your customers that have access; customers of others keep theirs. Without user_ids, the users stay as they are.

curl -X PATCH https://www.spamfactor.com/api/v1/domains/5 \
  -H "Authorization: Bearer sf_key_..." -H "Content-Type: application/json" \
  -d '{"greylisting": true}'

DELETE/domains/{id}

Delete a domain

The filter refuses mail for it at once. Answers 204 without body.

GET/users

List your users

Filter with ?role=customer, ?q= (part of the email address or name) or ?parent_id=. Paginated.

GET/users/{id}

One user

With their domains, addresses, parent and whether they use two-factor authentication.

POST/users

Create a user

The user can log in at once. Users you make belong to you.

curl -X POST https://www.spamfactor.com/api/v1/users \
  -H "Authorization: Bearer sf_key_..." -H "Content-Type: application/json" \
  -d '{"email": "jan@example.com", "password": "a-long-password", "role": "customer", "domain_ids": [5]}'

PATCH/users/{id}

Change a user

Only the fields you send. Without domain_ids or addresses, those stay as they are. Leave out password to keep it. Set active to false to block someone without deleting them.

DELETE/users/{id}

Delete a user

Not possible while they still have users of their own (409). Answers 204 without body.

POST/users/{id}/reset-2fa

Reset two-factor authentication

For a user who lost their phone: removes their authenticator app, passkeys and recovery codes, so they can log in with just their password and set it up again.

GET/messages

List messages

Newest first. A message that has a stored copy has a quarantine_id.

curl -H "Authorization: Bearer sf_key_..." "https://www.spamfactor.com/api/v1/messages?days=1&status=blocked"

{
    "data": [{
        "id": "1791470458-15666056831403781299",
        "received_at": "2026-10-08T16:40:58+02:00",
        "sender": "offers@example.ru",
        "recipients": ["sales@example.com"],
        "subject": "Special offer just for you!",
        "score": 9.6,
        "status": "blocked",
        "quarantine_id": "ca5a1450-6b84-4c5b-9449-5b027e2b0d58"
    }],
    "meta": { "page": 1, "per_page": 25, "total": 1, "pages": 1 }
}

GET/messages/{id}

One message

Everything the filter found: the rules with their scores, DKIM, SPF, DMARC and Bayes, and the stored copy when there is one.

GET/quarantine

List quarantined messages

Newest first.

GET/quarantine/{id}

One quarantined message

With its headers, text body, and per recipient whether it was released. delivery says per recipient what their mail server answered (sent, deferred, bounced or expired, with the answer), for the message itself and for every release in releases.

GET/quarantine/{id}/body

The message as HTML page

For showing the message. Scripts, forms and remote images are blocked.

GET/quarantine/{id}/raw

The original message

As .eml file (message/rfc822).

POST/quarantine/{id}/release

Release a message

Delivers it to the recipients you may see. Released mail is not scanned again, so only release what you trust.

curl -X POST https://www.spamfactor.com/api/v1/quarantine/ca5a1450-6b84-4c5b-9449-5b027e2b0d58/release \
  -H "Authorization: Bearer sf_key_..." -H "Content-Type: application/json" -d '{"learn": true}'

POST/quarantine/bulk

Release or train several messages

At most 100 at once. Answers how many were done, and why the others were not.

{ "data": { "done": 9, "failed": 1, "errors": { "This message could not be found.": 1 }, "message": "..." } }

POST/quarantine/{id}/learn/spam

This is spam

Works for quarantined messages and for stored copies of delivered mail (the quarantine_id of a message).

POST/quarantine/{id}/learn/ham

This is not spam

This does not deliver the message: use release for that.

POST/uploads/check

Which message is this?

Finds the message without learning anything.

POST/uploads/learn/spam

This message from a mailbox is spam

Send the message as body with Content-Type: message/rfc822, or as multipart file file. Use uploads/learn/ham for not spam.

curl -X POST https://www.spamfactor.com/api/v1/uploads/learn/spam \
  -H "Authorization: Bearer sf_key_..." -H "Content-Type: message/rfc822" --data-binary @message.eml

GET/statistics

Totals and trends

Totals per status, a row per day, per domain, and the top rules, spam senders and countries. Takes days (default 30) and scope.

curl -H "Authorization: Bearer sf_key_..." "https://www.spamfactor.com/api/v1/statistics?days=30&scope=example.com"