Domains API

Manage sending and receiving domains, configure DNS records, and verify domain ownership.

Create Domain

POST /v1/domains

Register a new domain for sending or receiving email.

Use outbound when Postscale should send mail for a domain but another provider should keep receiving mail for it. Outbound-only domains do not require root MX records.

Request Body

Example Request

curl -X POST https://api.postscale.io/v1/domains \
  -H "Authorization: Bearer ps_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "type": "both",
    "catch_all_enabled": true
  }'

Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
	  "domain": "example.com",
	  "type": "both",
	  "verified": false,
	  "ownership_verified": false,
	  "mx_verified": false,
  "spf_verified": false,
  "dkim_verified": false,
  "dmarc_verified": false,
  "catch_all_enabled": true,
  "active": true,
  "last_dns_check": null,
  "verified_at": null,
  "created_at": "2026-01-18T10:30:00Z",
  "updated_at": "2026-01-18T10:30:00Z"
}

List Domains

GET /v1/domains

Retrieve all domains registered to your account.

Query Parameters

Example Request

curl -X GET "https://api.postscale.io/v1/domains?limit=20&offset=0" \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "domains": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
	      "domain": "example.com",
	      "type": "both",
	      "verified": true,
	      "ownership_verified": true,
	      "mx_verified": true,
      "spf_verified": true,
      "dkim_verified": true,
      "dmarc_verified": true,
      "catch_all_enabled": true,
      "active": true,
      "last_dns_check": "2026-01-18T12:00:00Z",
      "verified_at": "2026-01-18T10:35:00Z",
      "created_at": "2026-01-18T10:30:00Z",
      "updated_at": "2026-01-18T10:35:00Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Get Domain

GET /v1/domains/:id

Retrieve details for a specific domain. The :id parameter accepts either a UUID or a domain name.

Example Request

curl -X GET https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
	  "domain": "example.com",
	  "type": "both",
	  "verified": true,
	  "ownership_verified": true,
	  "mx_verified": true,
  "spf_verified": true,
  "dkim_verified": true,
  "dmarc_verified": true,
  "catch_all_enabled": true,
  "active": true,
  "last_dns_check": "2026-01-18T12:00:00Z",
  "verified_at": "2026-01-18T10:35:00Z",
  "created_at": "2026-01-18T10:30:00Z",
  "updated_at": "2026-01-18T10:35:00Z"
}

Update Domain

PUT /v1/domains/:id

Update an existing domain's configuration. All fields are optional -- only provided fields will be updated.

Request Body

Example Request

curl -X PUT https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer ps_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "catch_all_enabled": false,
    "active": true
  }'

Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
	  "domain": "example.com",
	  "type": "both",
	  "verified": true,
	  "ownership_verified": true,
	  "mx_verified": true,
  "spf_verified": true,
  "dkim_verified": true,
  "dmarc_verified": true,
  "catch_all_enabled": false,
  "active": true,
  "last_dns_check": "2026-01-18T12:00:00Z",
  "verified_at": "2026-01-18T10:35:00Z",
  "created_at": "2026-01-18T10:30:00Z",
  "updated_at": "2026-01-18T14:00:00Z"
}

Delete Domain

DELETE /v1/domains/:id

Remove a domain from your account. This will stop all email sending and receiving for the domain.

Example Request

curl -X DELETE https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "status": "deleted"
}

Verify Domain

POST /v1/domains/:id/verify

Trigger DNS verification for a domain. This checks ownership TXT, MX, SPF, DKIM, DMARC, and return-path records where applicable. A domain is considered verified when ownership is confirmed and the records required for its type are valid: outbound requires SPF, inbound and alias require MX, and both requires MX plus SPF. Sending also requires verified DKIM. The return-path CNAME is recommended for production outbound traffic but does not make the root domain receive mail through Postscale.

Example Request

curl -X POST https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/verify \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "verified": true,
  "ownership_verified": true,
  "mx_verified": true,
  "spf_verified": true,
  "dkim_verified": true,
  "dmarc_verified": false,
  "verified_at": "2026-01-18T12:00:00Z",
  "summary": "Domain verified. MX, SPF, and DKIM records are valid. DMARC record not found.",
  "mx_records": ["mx.postscale.io"],
  "spf_record": "v=spf1 include:_spf.postscale.io ~all",
  "return_path": {
    "hostname": "ps-bounces.example.com",
    "cname_target": "bounces.postscale.io",
    "verified": true,
    "required_for": "production_outbound",
    "delayed_bounce_tracking_enabled": true
  },
  "return_path_verified": true,
  "delayed_bounce_tracking_enabled": true
}

When verification fails, the response includes error details for each failing record:

{
  "verified": false,
  "ownership_verified": false,
  "mx_verified": false,
  "spf_verified": false,
  "dkim_verified": false,
  "dmarc_verified": false,
  "verified_at": "2026-01-18T12:00:00Z",
  "summary": "Verification failed. Ownership not confirmed. MX, SPF, DKIM records missing.",
  "ownership_error": "TXT record not found for _postscale.example.com",
  "mx_error": "No MX records found pointing to postscale.io",
  "spf_error": "SPF record found but missing 'include:_spf.postscale.io'",
  "dkim_error": "DKIM record not found for postscale1._domainkey.example.com"
}

Get DNS Records

GET /v1/domains/:id/dns

Retrieve the DNS records that must be configured at your DNS provider for a domain to pass verification. Outbound-only domains do not require root MX; inbound-capable domains do. Outbound-capable domains also return a return-path CNAME for delayed bounce tracking.

Example Request

curl -X GET https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/dns \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
	  "domain": "example.com",
	  "verified": false,
	  "ownership_verified": false,
	  "mx_verified": false,
  "spf_verified": false,
  "dkim_verified": false,
  "dmarc_verified": false,
  "records": [
    {
      "type": "TXT",
      "name": "_postscale.example.com",
      "value": "postscale-verification=your_verification_token",
      "status": "pending",
      "purpose": "Domain ownership verification"
    },
    {
      "type": "MX",
      "name": "example.com",
      "value": "mx.postscale.io",
      "priority": 10,
      "status": "pending",
      "purpose": "Inbound mail routing"
    },
    {
      "type": "TXT",
      "name": "example.com",
      "value": "v=spf1 include:_spf.postscale.io ~all",
      "status": "pending",
      "purpose": "SPF authentication"
    },
    {
      "type": "CNAME",
      "name": "postscale1._domainkey.example.com",
      "value": "postscale1.dkim.postscale.io",
      "status": "pending",
      "purpose": "DKIM email signing"
    },
    {
      "type": "TXT",
      "name": "_dmarc.example.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@postscale.io",
      "status": "recommended",
      "purpose": "DMARC policy"
    },
    {
      "type": "CNAME",
      "name": "ps-bounces.example.com",
      "value": "bounces.postscale.io",
      "status": "pending",
      "purpose": "Return-Path CNAME for delayed bounce tracking"
    }
  ],
  "return_path": {
    "hostname": "ps-bounces.example.com",
    "cname_target": "bounces.postscale.io",
    "verified": false,
    "required_for": "production_outbound",
    "delayed_bounce_tracking_enabled": false
  },
  "return_path_verified": false,
  "delayed_bounce_tracking_enabled": false
}

Domain Types

Domain Verification Fields