API Documentation

Integrate BetterSpam into your mail infrastructure

Authentication

All API requests require authentication via API key or OAuth session.

X-API-Key: your-api-key

Endpoints

Email Lookup

GET /api/v1/lookup/email/{email}

Check email address reputation for spam and phishing indicators.

curl -H "X-API-Key: your-key" \\ https://betterspam.com/api/v1/lookup/email/test@example.com

Domain Lookup

GET /api/v1/lookup/domain/{domain}

Check domain reputation, DNS security (SPF, DMARC), and spam indicators.

curl -H "X-API-Key: your-key" \\ https://betterspam.com/api/v1/lookup/domain/example.com

IP Lookup

GET /api/v1/lookup/ip/{ip}

Check IP address reputation across multiple spam blacklists.

curl -H "X-API-Key: your-key" \\ https://betterspam.com/api/v1/lookup/ip/1.2.3.4

Message Check

POST /api/v1/mail/check

Check complete email message for spam using Rspamd, SpamAssassin, and BetterPhish.

curl -X POST -H "X-API-Key: your-key" \\ -H "Content-Type: application/json" \\ -d '{"message": "raw email content"}' \\ https://betterspam.com/api/v1/mail/check

Bulk Lookup

POST /api/v1/lookup/bulk

Check multiple items in a single request (max 100 items for free tier).

curl -X POST -H "X-API-Key: your-key" \\ -H "Content-Type: application/json" \\ -d '{"emails": ["test1@example.com", "test2@example.com"]}' \\ https://betterspam.com/api/v1/lookup/bulk

Response Format

All responses are in JSON format with the following structure:

{ "email": "test@example.com", "domain": "example.com", "checked_at": "2026-02-21T12:00:00Z", "sources": { "rspamd": {...}, "amavisd": {...}, "betterphish": {...} }, "summary": { "is_spam": false, "is_phishing": false, "reputation": "clean", "risk_score": 0, "confidence": 0.95 } }

Integration Examples

Postfix Integration

Use BetterSpam as a policy server in Postfix:

# /etc/postfix/main.cf smtpd_recipient_restrictions = check_policy_service inet:betterspam.com:10040

Rspamd Integration

Configure Rspamd to check BetterSpam API:

# /etc/rspamd/local.d/external_services.conf betterspam { url = "https://betterspam.com/api/v1/mail/check"; api_key = "your-key"; }

Python Client

import requests api_key = "your-key" headers = {"X-API-Key": api_key} response = requests.get( "https://betterspam.com/api/v1/lookup/email/test@example.com", headers=headers ) data = response.json() print(f"Reputation: {data['summary']['reputation']}")