Skip to content

ResourcesDomains

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

POST/v1/domainsscope domains:writetier write

Request body

FieldTypeRequiredDescription
namestringYesDomain 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

GET/v1/domains

Scope: domains:read. Rate limit tier: read. Page with cursor and limit.

Retrieve a domain

GET/v1/domains/:id

Scope: domains:read. Returns the domain object or 404.

Retrieve DNS records

GET/v1/domains/:id/dns-records

Scope: 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

GET/v1/domains/:id/health

Scope: 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
      }
    ]
  }
}
  • dns and blocklist come from the check Shipmail runs every 6 hours. This endpoint does not run a new DNS check. For a live one, use GET /v1/domains/:id/dns-records.
  • delivery counts 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) and other. A provider with no recipients is left out.
  • delivery_rate is 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 is null until at least one recipient has one.

Update a domain

PATCH/v1/domains/:idscope domains:writetier write

Request body

FieldTypeDescription
catch_all_mailbox_idstring | nullAny active mailbox ID in the same organization, even one on another domain. Set null to turn catch-all off.

Delete a domain

DELETE/v1/domains/:id

Scope: domains:write. Returns 204 with no body. Deleting a domain also deletes its mailboxes and its DNS configuration.

Verify a domain

POST/v1/domains/:id/verification

Scope: 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

POST/v1/domains/search

Scope: domains:read. Rate limit tier: read. Finds domain names you can register through Shipmail, with their availability and price.

Request body

FieldTypeRequiredDescription
keywordstringYesWord 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

POST/v1/domains/register

Scope: 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

FieldTypeRequiredDescription
namestringYesDomain name to register, e.g. example.com.
yearsintegerNoRegistration period in years, 1 to 10. Defaults to 1.
contactobjectYesRegistrant 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.