API ReferenceCopy Anchor Link

The NorthRelay API lets you send transactional and marketing emails, manage domains, templates, contacts, mailing-list subscriptions, suppressions, and retrieve analytics programmatically.

Base URLCopy Anchor Link

All API requests use the following base URL:

https://app.northrelay.ca/api/v1/

All requests must be made over HTTPS. Plain HTTP requests are rejected.

AuthenticationCopy Anchor Link

Authenticate every request with a Bearer token in the Authorization header:

curl https://app.northrelay.ca/api/v1/emails/send \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API keys use two prefixes:

Create and manage keys in Dashboard > Settings > API Keys. See the Authentication page for full details.

Rate LimitsCopy Anchor Link

Sending quotas are enforced per account based on your plan tier. They are expressed as recipients per calendar month and reset on the 1st:

When you exceed your monthly quota, the API returns a 429 status with the QUOTA_EXCEEDED error code and the date the counter resets. Upgrading raises the limit immediately.

API request rate limits (separate from email quotas):

Error HandlingCopy Anchor Link

Every error response follows a consistent JSON structure with four fields:

{
  "code": "DOMAIN_NOT_FOUND",
  "message": "The specified domain was not found",
  "action": "Check the domain ID and try again",
  "docs_url": "https://docs.northrelay.ca/domains/setup"
}

HTTP Status CodesCopy Anchor Link

Error Codes ReferenceCopy Anchor Link

PaginationCopy Anchor Link

List endpoints return paginated results. Control pagination with query parameters:

Every paginated response includes a pagination object:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "totalPages": 6
  }
}

VersioningCopy Anchor Link

The API is versioned via the URL path (/api/v1/). Breaking changes will be introduced under a new version prefix (e.g., /api/v2/). Non-breaking additions (new fields, new endpoints) are added to the current version without a version bump.

Content TypeCopy Anchor Link

All request bodies must be JSON with the Content-Type: application/json header. All responses are JSON.

Next StepsCopy Anchor Link

• Authentication -- create and use API keys
• Sending -- send single, batch, and scheduled emails
• Domains -- add and verify custom sending domains
• Templates -- manage reusable email templates
• Webhooks -- receive delivery event notifications