Domains API
Add your own domain, like example.com, so its mailboxes can send and receive email. The domain goes active once Shipmail verifies its DNS records.
Last updated
The domain object
{
"object": "domain",
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"name": "example.com",
"status": "verified",
"managed_by": "external",
"dns_provider": "cloudflare",
"mx_verified": true,
"spf_verified": true,
"dkim_verified": true,
"dmarc_verified": true,
"dmarc_managed_externally": false,
"outbound_verified": true,
"catch_all_mailbox_id": null,
"verified_at": "2025-01-15T10:30:00.000Z",
"created_at": "2025-01-15T10:00:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z"
}Create a domain
/v1/domainsscope domains:writetier writeRequest body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Domain name, e.g. example.com. Max 253 characters. |
Example
curl -X POST https://shipmail.to/api/v1/domains \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{"name": "example.com"}'Returns the domain object with status 201.
List domains
/v1/domainsScope: domains:read. Rate limit tier: read. Page with cursor and limit.
Retrieve a domain
/v1/domains/:idScope: domains:read. Returns the domain object or 404.
Retrieve DNS records
/v1/domains/:id/dns-recordsScope: domains:read. Rate limit tier: verification (1 request per minute). Returns the DNS records the domain needs. Each one has a live status and the values Shipmail finds in DNS right now. Use it to set up DNS from a script, or to see why a check failed.
curl https://shipmail.to/api/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/dns-records \
-H "Authorization: Bearer sm_live_..."
{
"object": "dns_record_set",
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"domain_name": "example.com",
"all_verified": false,
"checked_at": "2026-07-13T16:00:00.000Z",
"records": [
{
"key": "mx",
"type": "MX",
"host": "@",
"value": "mx1.shipmail.to",
"priority": 10,
"ttl": 300,
"status": "verified",
"found_values": ["mx1.shipmail.to"]
}
]
}The response contains MX, SPF, custom MAIL FROM MX and SPF, DKIM, and DMARC records. Record status is verified, not_found, mismatch, or pending. A record is pending until Shipmail has generated its value.
Retrieve domain health
/v1/domains/:id/healthScope: domains:read. Rate limit tier: read. Returns the domain's health in one call. It tells you whether its MX, SPF, DKIM and DMARC records pass, whether the Spamhaus Domain Block List lists it, and how delivery from its mailboxes went over the last 30 days.
curl https://shipmail.to/api/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/health \
-H "Authorization: Bearer sm_live_..."
{
"object": "domain_health",
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"domain": "example.com",
"generated_at": "2026-10-18T12:00:00.000Z",
"dns": {
"mx": true,
"spf": true,
"dkim": true,
"dmarc": false,
"last_checked_at": "2026-10-18T06:00:00.000Z"
},
"blocklist": { "list": "spamhaus_dbl", "listed": false, "listed_since": null },
"delivery": {
"since": "2026-09-18T12:00:00.000Z",
"until": "2026-10-18T12:00:00.000Z",
"recipients": 1250,
"delivered": 1228,
"bounced": 9,
"deferred": 4,
"complained": 1,
"failed": 0,
"suppressed": 6,
"queued": 0,
"sent": 2,
"delivery_rate": 98.9,
"providers": [
{
"provider": "google",
"recipients": 740,
"delivered": 734,
"bounced": 3,
"deferred": 1,
"complained": 1,
"delivery_rate": 99.5
}
]
}
}dnsandblocklistcome from the check Shipmail runs every 6 hours. This endpoint does not run a new DNS check. For a live one, useGET /v1/domains/:id/dns-records.deliverycounts the recipients of messages sent from the domain's mailboxes in the last 30 days, in total and per recipient provider:google(Gmail),microsoft(Outlook),yahoo,apple(iCloud) andother. A provider with no recipients is left out.delivery_rateis a percentage from 0 to 100 with one decimal. It is delivered plus complained recipients, divided by the recipients that have a final outcome. It isnulluntil at least one recipient has one.
Update a domain
/v1/domains/:idscope domains:writetier writeRequest body
| Field | Type | Description |
|---|---|---|
| catch_all_mailbox_id | string | null | Any active mailbox ID in the same organization, even one on another domain. Set null to turn catch-all off. |
Delete a domain
/v1/domains/:idScope: domains:write. Returns 204 with no body. Deleting a domain also deletes its mailboxes and its DNS configuration.
Verify a domain
/v1/domains/:id/verificationScope: domains:read. Rate limit tier: verification (1 request per minute). Runs a DNS check now and returns the updated domain object.
Subscribe to the domain.verified and domain.verification_failed webhook events instead of polling this endpoint.
Managed vs external domains
The managed_by field says who manages the domain's DNS.
external: your DNS lives at your own provider. You add the records there yourself, then verify them.shipmail: you registered the domain through Shipmail, and Shipmail sets up its DNS records for you.
Search domains
/v1/domains/searchScope: domains:read. Rate limit tier: read. Finds domain names you can register through Shipmail, with their availability and price.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| keyword | string | Yes | Word to build domain names from, e.g. mycompany. |
Example
curl -X POST https://shipmail.to/api/v1/domains/search \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{"keyword": "mycompany"}'Returns an object with a results array. Each result includes domain_name, available, purchase_price, renewal_price, and currency.
Register a domain
/v1/domains/registerScope: domains:write. Rate limit tier: write. Buys a domain through Shipmail. It charges the saved payment method and returns the new Domain object. You need an active subscription. Shipmail sets up the DNS records.
Only an API key created by a person can buy. An agent credential (an OAuth connection, the MCP server over OAuth, or an agent registration) is never charged. It gets a 403 with reason: "owner_confirmation_required" and an action_url where the organization owner reviews the price and confirms the purchase.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Domain name to register, e.g. example.com. |
| years | integer | No | Registration period in years, 1 to 10. Defaults to 1. |
| contact | object | Yes | Registrant contact information: first_name, last_name, address1, address2, city, state, zip, country (ISO 3166-1 alpha-2), phone (E.164), email. |
Example
curl -X POST https://shipmail.to/api/v1/domains/register \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "mycompany.com",
"years": 1,
"contact": {
"first_name": "Jane",
"last_name": "Doe",
"address1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US",
"phone": "+14155551234",
"email": "jane@example.com"
}
}'Returns a Domain object (201) with managed_by: "shipmail", and Shipmail sets up its DNS records. Returns 402 if the payment fails, and 403 if there is no active subscription. A name that looks like a well-known brand's, such as paypal-secure-login.com, also returns 403: a person reviews it before it can be registered, nothing is charged, and you can retry once it is approved.
Returns 409 with type conflict when the domain is already in Shipmail, a purchase for it is already running, or support closed the purchase before registration. In that last case, contact support for a refund.
Returns 409 with type reconciliation_required when the purchase isn't settled yet. That happens when the payment is still processing, Stripe didn't confirm the payment, the registrar didn't confirm the registration, or the domain was registered but couldn't be saved. Don't retry. The name stays reserved and you are never charged twice for it. If the payment is processing, the domain is registered once it clears. Otherwise Shipmail checks the payment and the registrar, then finishes the setup or refunds you.