Email API

Endpoints under the /api/v1/email base path. This page covers the public one-click unsubscribe handler and the authenticated recipient validation (list-hygiene) endpoints. Sending email goes through the unified Messaging API. Base path: /api/v1/email

Unsubscribe

The public one-click unsubscribe surface that the List-Unsubscribe and List-Unsubscribe-Post headers in outbound email reference. RFC 8058 compliant. Authentication: HMAC-token (embedded in URL). Not Clerk-authenticated — these URLs are designed to be opened by the recipient’s mail client without any session.

Method	Path	Purpose
`GET`	`/api/v1/email/unsubscribe/{token}`	Render the unsubscribe page
`POST`	`/api/v1/email/unsubscribe/{token}`	Process one-click unsubscribe (RFC 8058)

You don’t typically call these endpoints from your own application — Orbit injects the URLs into outbound email automatically.

Recipient validation

Real-time recipient list-hygiene checks (SendGrid Email Validation API parity). Score an address before you send to it: syntax, disposable-domain and role-account detection, MX presence, a likely-typo correction, and an aggregate 0–1 risk score with a coarse low/medium/high band. Pure DNS + heuristics — no SMTP mailbox probing and no third-party feed. Addresses are not persisted (transient validation only). Authentication: standard workspace auth (X-API-Key or dashboard session). Both endpoints require an authenticated workspace, but the auth level differs: single-address POST /email/validate additionally requires an owner or admin role, while POST /email/validate/bulk is open to any authenticated workspace member. A non-admin caller hitting POST /email/validate gets a 403.

Method	Path	Auth	Purpose
`POST`	`/api/v1/email/validate`	`owner` / `admin` role	Validate a single recipient address
`POST`	`/api/v1/email/validate/bulk`	Any workspace member	Validate a list of addresses in one call (max 1000)

POST /api/v1/email/validate

Requires an owner or admin role. A workspace member without one of these roles receives a 403. Request body:

{ "email": "user@example.com" }

Response data:

Field	Type	Description
`email`	string	The input, lower-cased + trimmed
`valid`	boolean	Syntactically sound and able to receive mail (a definitive no-MX flips this `false`)
`disposable`	boolean	Known disposable / throwaway provider
`role_based`	boolean	Role/group mailbox (`info@`, `support@`, …) rather than a person
`mx_found`	boolean \| null	Domain publishes a usable MX. `null` = lookup timed out (unknown, not a verdict)
`risk_score`	number	Aggregate `0`–`1` deliverability-risk score (higher = riskier)
`risk_band`	string	`low` \| `medium` \| `high`, derived from `risk_score`
`suggested_correction`	string \| null	A corrected address for a likely typo (e.g. `user@gmial.con` → `user@gmail.com`)
`reasons`	string[]	Short, human-readable notes explaining the verdict

POST /api/v1/email/validate/bulk

Available to any authenticated workspace member — no owner/admin role required. Validate up to 1000 addresses in one call. Input is de-duplicated case-insensitively before scoring. Request body:

{ "emails": ["alice@example.com", "support@example.com"] }

Response data:

{
  "summary": { "total": 2, "valid": 2, "invalid": 0, "risky": 1 },
  "results": [
    {
      "email": "alice@example.com",
      "valid": true,
      "reason": "deliverable",
      "mx_verified": true,
      "risk": "low",
      "risk_score": 0,
      "disposable": false,
      "role_based": false,
      "suggested_correction": null
    }
  ]
}

Each row carries a single machine-readable reason code — one of deliverable, invalid_syntax, no_mx_record, disposable_domain, role_account, possible_typo, or mx_unknown — so importers can branch deterministically. The summary.risky count is the number of deliverable but flagged rows (disposable / role / typo / non-low band) a sender should review before importing.

API Reference

All Endpoints

Email API

Email API

Unsubscribe

Recipient validation

POST /api/v1/email/validate

POST /api/v1/email/validate/bulk

See also

​Email API

​Unsubscribe

​Recipient validation

​POST /api/v1/email/validate

​POST /api/v1/email/validate/bulk

​See also

Email API

Unsubscribe

Recipient validation

POST /api/v1/email/validate

POST /api/v1/email/validate/bulk

See also