# ShieldMX

> ShieldMX stops free-trial abuse at signup. You send one email address and get back JSON with a recommendation of ALLOW, REVIEW or REJECT, a reason, and a risk score from 0 to 100. It checks the RFC 5322 syntax, matches the exact domain and its parents against a list of disposable providers refreshed daily, looks up the domain's mail server, flags privacy alias services, and suggests a fix for common provider typos.

ShieldMX is in early access.

## Verdicts

- REJECT with reason disposable_domain: the domain is a known disposable provider (risk 100).
- REJECT with reason no_mail_server: the domain has no mail server (risk 90).
- REJECT with reason customer_denied: the customer added a deny rule for the domain (risk 100).
- REVIEW with reason privacy_alias: a privacy alias service such as Firefox Relay or SimpleLogin (risk 50). Ask for another check instead of refusing.
- ALLOW with reason clean: nothing matched (risk 0).
- ALLOW with reason customer_allowed: the customer added an allow rule for the domain (risk 0).

Customer allow and deny rules cover the domain and its subdomains, and the most specific rule wins.

## Endpoints

- POST https://shieldmx-core-api.slotboard-v.workers.dev/v1/verify (one address)
- POST https://shieldmx-core-api.slotboard-v.workers.dev/v1/verify/batch (up to 100 addresses)
- Header: Authorization: Bearer <API key>
- Body: {"email": "someone@example.com"}
- Add ?mx=false to skip the mail-server lookup.

## Errors

- 400 INVALID_SYNTAX, MALFORMED_JSON, INVALID_BATCH
- 401 UNAUTHORIZED
- 429 RATE_LIMITED (60 requests a minute per key) or QUOTA_EXCEEDED
- 503 AUTH_UNAVAILABLE or BLOCKLIST_UNAVAILABLE. A 503 means the check did not run. It does not mean the address is valid.

## Documentation

- Full API reference: https://shieldmx.pages.dev/docs/
- OpenAPI 3.1 contract: https://shieldmx-core-api.slotboard-v.workers.dev/openapi.json

## Contact

- heysharad@proton.me