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.

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,
  "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,
      "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,
  "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,
  "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 that all required DNS records (MX, SPF, DKIM, DMARC) are correctly configured. A domain is considered verified when ownership is confirmed and both MX and SPF records are valid.

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": ["mx1.postscale.io", "mx2.postscale.io"],
  "spf_record": "v=spf1 include:_spf.postscale.io ~all"
}

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 does not 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 required DNS records that must be configured at your DNS provider for a domain to pass verification.

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,
  "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": "mx1.postscale.io",
      "priority": 10,
      "status": "pending",
      "purpose": "Inbound mail routing"
    },
    {
      "type": "MX",
      "name": "example.com",
      "value": "mx2.postscale.io",
      "priority": 20,
      "status": "pending",
      "purpose": "Inbound mail routing (fallback)"
    },
    {
      "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"
    }
  ]
}

Domain Types

Domain Verification Fields