Domains API

Custom sending domains let you send emails from your own domain (e.g., hello@yourdomain.com) instead of a NorthRelay system subdomain. Custom domains require proper DNS configuration for SPF, DKIM, and DMARC.

Tier requirement: Custom domains are available on Starter ($5/mo) and above. The Free tier sends from a NorthRelay system subdomain only.

Tier	Custom Domain Limit
Free	0
Starter	1
Micro	2
Pro	5
Scale	20
Enterprise	Unlimited

List Domains

Retrieve all domains associated with your account.

GET /domains

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`25`	Items per page (max 100)
`status`	string	--	Filter by status: `pending`, `verified`, `failed`

Example Request

curl https://app.northrelay.ca/api/v1/domains \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "dom_a1b2c3d4",
      "hostname": "yourdomain.com",
      "status": "verified",
      "isInboxHosted": false,
      "dnsRecords": {
        "spf": { "status": "verified", "value": "v=spf1 include:_spf.north-pipe.ca -all" },
        "dkim": { "status": "verified", "selector": "default" },
        "dmarc": { "status": "verified", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" },
        "verification": { "status": "verified", "value": "northrelay-verify=dom_a1b2c3d4" }
      },
      "createdAt": "2026-03-01T10:00:00.000Z",
      "verifiedAt": "2026-03-01T10:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}

Get Domain

Retrieve details for a single domain.

GET /domains/{id}

Example Request

curl https://app.northrelay.ca/api/v1/domains/dom_a1b2c3d4 \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

Returns the same domain object structure as the list endpoint.

Add Domain

POST /domains

Request Body

Field	Type	Required	Description
`hostname`	string	Yes	Domain name (e.g., `yourdomain.com`)

Example Request

curl -X POST https://app.northrelay.ca/api/v1/domains \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "hostname": "yourdomain.com" }'

Example Response

{
  "id": "dom_a1b2c3d4",
  "hostname": "yourdomain.com",
  "status": "pending",
  "dnsRecords": {
    "verification": {
      "type": "TXT",
      "host": "yourdomain.com",
      "value": "northrelay-verify=dom_a1b2c3d4",
      "status": "pending"
    },
    "spf": {
      "type": "TXT",
      "host": "yourdomain.com",
      "value": "v=spf1 include:_spf.north-pipe.ca -all",
      "status": "pending"
    },
    "dkim": {
      "type": "TXT",
      "host": "default._domainkey.yourdomain.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkq...",
      "status": "pending"
    },
    "dmarc": {
      "type": "TXT",
      "host": "_dmarc.yourdomain.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com",
      "status": "pending"
    }
  },
  "createdAt": "2026-03-19T14:30:00.000Z"
}

Error: Domain Limit Reached

{
  "code": "API_KEY_LIMIT_REACHED",
  "message": "You have reached the maximum number of custom domains for your plan",
  "action": "Upgrade to a higher tier to add more domains.",
  "docs_url": "https://docs.northrelay.ca/api-keys/limits"
}

DNS Record Requirements

After adding a domain, configure these four DNS records at your DNS provider:

1. Verification TXT Record

Proves domain ownership. Required before any other records are checked.

Field	Value
Type	`TXT`
Host	`yourdomain.com`
Value	`northrelay-verify=dom_a1b2c3d4`
TTL	300 (or lowest available)

2. SPF Record

Authorizes NorthRelay relay IPs to send on your behalf.

Field	Value
Type	`TXT`
Host	`yourdomain.com`
Value	`v=spf1 include:_spf.north-pipe.ca -all`

If you have an existing SPF record, add include:_spf.north-pipe.ca before the all mechanism. Only one SPF record per domain is allowed.

3. DKIM Record

Enables cryptographic signing of outbound emails. The public key is provided when you add the domain.

Field	Value
Type	`TXT`
Host	`default._domainkey.yourdomain.com`
Value	Provided in the Add Domain response

4. DMARC Record

Tells receiving servers how to handle authentication failures.

Field	Value
Type	`TXT`
Host	`_dmarc.yourdomain.com`
Value	`v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com`

Replace dmarc@yourdomain.com with the address where you want to receive DMARC aggregate reports.

Verify Domain

Trigger DNS verification for a domain. NorthRelay checks all four DNS records and updates their status.

POST /domains/{id}/verify

Example Request

curl -X POST https://app.northrelay.ca/api/v1/domains/dom_a1b2c3d4/verify \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response (Success)

{
  "id": "dom_a1b2c3d4",
  "hostname": "yourdomain.com",
  "status": "verified",
  "dnsRecords": {
    "verification": { "status": "verified" },
    "spf": { "status": "verified" },
    "dkim": { "status": "verified" },
    "dmarc": { "status": "verified" }
  },
  "verifiedAt": "2026-03-19T14:35:00.000Z"
}

Example Response (Partial Failure)

{
  "id": "dom_a1b2c3d4",
  "hostname": "yourdomain.com",
  "status": "pending",
  "dnsRecords": {
    "verification": { "status": "verified" },
    "spf": { "status": "verified" },
    "dkim": { "status": "pending" },
    "dmarc": { "status": "pending" }
  },
  "verifiedAt": null
}

The domain status remains pending until all four records pass verification. You can call this endpoint repeatedly as you configure records.

Common Verification Errors

Error Code	Cause	Fix
`DNS_VERIFICATION_FAILED`	Verification TXT record not found	Add the TXT record and wait for DNS propagation (up to 48 hours)
`DNS_RECORD_MISSING`	SPF, DKIM, or DMARC record missing	Add the missing record per the instructions above
`DNS_LOOKUP_ERROR`	DNS query failed	Check that the domain resolves and your DNS provider is reachable

Delete Domain

Remove a custom domain. This immediately stops sending from that domain. Emails already queued may still be delivered.

DELETE /domains/{id}

Example Request

curl -X DELETE https://app.northrelay.ca/api/v1/domains/dom_a1b2c3d4 \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example Response

{
  "id": "dom_a1b2c3d4",
  "deleted": true
}

Domain Object Reference

Field	Type	Description
`id`	string	Unique domain identifier
`hostname`	string	Domain name
`status`	string	`pending`, `verified`, or `failed`
`isInboxHosted`	boolean	Whether catch-all inbox hosting is enabled
`dnsRecords`	object	Status of each DNS record (verification, SPF, DKIM, DMARC)
`createdAt`	string	ISO 8601 creation timestamp
`verifiedAt`	string \| null	ISO 8601 verification timestamp

Domains API

Domains APICopy Anchor Link

List DomainsCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Get DomainCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Add DomainCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Error: Domain Limit ReachedCopy Anchor Link

DNS Record RequirementsCopy Anchor Link

1. Verification TXT RecordCopy Anchor Link

2. SPF RecordCopy Anchor Link

3. DKIM RecordCopy Anchor Link

4. DMARC RecordCopy Anchor Link

Verify DomainCopy Anchor Link

Example RequestCopy Anchor Link

Example Response (Success)Copy Anchor Link

Example Response (Partial Failure)Copy Anchor Link

Common Verification ErrorsCopy Anchor Link

Delete DomainCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Domain Object ReferenceCopy Anchor Link

On this page

Domains API

List Domains

Query Parameters

Example Request

Example Response

Get Domain

Example Request

Example Response

Add Domain

Request Body

Example Request

Example Response

Error: Domain Limit Reached

DNS Record Requirements

1. Verification TXT Record

2. SPF Record

3. DKIM Record

4. DMARC Record

Verify Domain

Example Request

Example Response (Success)

Example Response (Partial Failure)

Common Verification Errors

Delete Domain

Example Request

Example Response

Domain Object Reference