Sending domains API

Use the current sending-domain API

These dashboard endpoints require an authenticated agent session JWT in Authorization: Bearer. A Verify, messaging, or MCP connection key does not grant access to them. Requests stay within the authenticated workspace.

All routes on this page require admin access. The current dashboard uses /api/v1/sending-domains. The older singular /api/v1/email/domain routes remain a separate compatibility surface; do not mix their IDs or response shapes with these routes.

List domains and DNS records

GET /api/v1/sending-domains returns { domains: [...] }. Each domain includes id, domain, status, sendable, returnPathHost, dkimStatus, spfStatus, dmarcStatus, createdAt, verifiedAt, lastCheckedAt, records and addresses. Each DNS record has id, type, host, value, priority, ttl, purpose and verified. Each address includes id, address, departmentId, displayName and status.

curl 'https://app.message.com/api/v1/sending-domains' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT'

Register your domain

POST /api/v1/sending-domains accepts { domain: "example.com" }. A new domain returns HTTP 201 with { domain: {...} }. Re-adding an existing domain in the same workspace returns its current bundle with HTTP 200. Registration does not mean DNS is verified or mail can be sent.

curl 'https://app.message.com/api/v1/sending-domains' \
  -H 'Authorization: Bearer YOUR_AGENT_JWT' \
  -H 'Content-Type: application/json' \
  --data '{"domain":"example.com"}'

Copy the exact returned DNS records

Use each returned record’s type, host, value and priority. The values are specific to your domain and may change; this guide deliberately does not provide substitute DNS values. The MX record used for sending is for the return-path/bounce host, not an instruction to replace your domain’s existing inbox MX records. Preserve the records used by Google Workspace, Microsoft 365 or your existing mail provider.

Domain verification enables sending. Receiving email is configured separately: create the department reply address and forward that mailbox to its Message.com forwarding destination. See the inbound-addresses API and the email setup screen.

Check verification

POST /api/v1/sending-domains/:id/verify refreshes DNS status and returns { domain: {...} }. Check sendable before sending. An optional retry=false query parameter avoids restarting an eligible failed verification. A 502 verification_unavailable means the check could not complete; saved records remain unchanged. It does not prove the records are wrong.

Remove a domain

DELETE /api/v1/sending-domains/:id returns { ok: true }. It removes the saved domain and archives the reply addresses tied to it. Review mail routing before removal. It does not remove records from your DNS provider.

Errors and recovery

Handle 400 invalid_body or invalid_domain, 403 permission errors, 404 not_found, 502 resend_error or verification_unavailable, and 503 resend_not_configured. Provider names may appear in error codes; display a helpful explanation in your UI and retain the code for diagnostics. Do not repeatedly register a domain as a substitute for checking its status.