Domains

Register a domain

Register a new domain through shipmail. Charges the saved payment method and returns the created Domain object. Requires an active subscription. Only an API key a person created can buy: an agent credential (an OAuth connection, the MCP server over OAuth, or an auth.md registration) never triggers a charge. It gets a 403 with reason: "owner_confirmation_required" and an action_url where the organization owner reviews the price and confirms the purchase.

post/domains/register

Request

  • Base URL: https://shipmail.to/api/v1
  • URL: https://shipmail.to/api/v1/domains/register
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://shipmail.to/api/auth/oauth2/authorize, token URL https://shipmail.to/api/auth/oauth2/token)

Headers

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Request body

namestring required

Domain name to register (e.g. example.com).

yearsinteger

Number of years to register for. Defaults to 1.

Response

Domain registered, DNS configured, and ready for mailboxes.

object'domain' required
idstring required
namestring required
status'pending' | 'verifying' | 'verified' | 'failed' | 'degraded' required
managed_by'external' | 'shipmail' required

Whether the domain is managed externally or registered through Shipmail.

dns_providerstring nullable required
mx_verifiedboolean required
spf_verifiedboolean required
dkim_verifiedboolean required
dmarc_verifiedboolean required

Whether the DMARC record was last seen as valid.

dmarc_managed_externallyboolean required

True if a non-shipmail DMARC record is already published for this domain.

outbound_verifiedboolean required
catch_all_mailbox_idstring nullable required

Active mailbox in the same organization receiving unmatched addresses, or null when catch-all is disabled. The mailbox may use another domain.

verified_atstring date-time nullable required
created_atstring date-time required
updated_atstring date-time required

Example response

{
  "name": "example.com",
  "registration": {
    "currency": "USD"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.