Subscriptions APICopy Anchor Link

The Subscriptions API is the one place to change who receives which mail. Use it from your own application to build newsletter signups, a preference page inside your product, or server-side opt-outs. Every call applies the same rules as NorthRelay's hosted forms, unsubscribe links and preference centre, and fires the same webhooks.

For a walkthrough of how the pieces fit together, see the Mailing Lists guide.

ConceptsCopy Anchor Link

Rules the API enforces for you:

• Subscribing to a topic means removing the recipient's opt-out for it. Opting out of a topic also removes the recipient from every list tagged with that topic.
• Unsubscribing from a list keeps the membership history (the membership is marked removed). Removing a member as the list owner deletes it (see list members).
• Someone who unsubscribed is never re-added silently. You must pass "resubscribe": true, and you should only do so after fresh consent.
• Bounce, complaint and manual suppressions are never lifted by a subscribe call.
• Contacts with status COMPLAINED or CLEANED cannot be resubscribed.

Authentication and scopesCopy Anchor Link

All endpoints in the first part of this page take an API key: Authorization: Bearer nr_live_.... Restricted keys need these scopes:

A key without the scope receives 403 SCOPE_INSUFFICIENT; a missing or invalid key receives 401.

The public endpoints for unsubscribe pages you host yourself (POST /unsubscribe, POST /unsubscribe/one-click) take the signed token from the unsubscribe link instead of an API key. See Unsubscribe links.

Response formatCopy Anchor Link

Successful responses use the standard envelope:

{ "success": true, "data": { } }

Errors include the fix:

{
  "success": false,
  "error": {
    "code": "RECIPIENT_UNSUBSCRIBED",
    "message": "jane@example.com has unsubscribed.",
    "fix_action": "The recipient unsubscribed. Pass \"resubscribe\": true only when they have given fresh consent (for example by submitting a form again), ideally with \"doubleOptIn\": true.",
    "docs_url": "https://docs.northrelay.ca/docs/api-reference/subscriptions"
  }
}

Validation errors use code VALIDATION_ERROR and name the offending field in error.context.field.

SubscribeCopy Anchor Link

Create or update a contact, add it to lists, opt it into topics and record consent. With doubleOptIn: true NorthRelay emails a confirmation link and the contact stays PENDING until the recipient clicks it.

POST /subscriptions

Returns 201 when the contact was created, 200 when it already existed. Repeating the same call is safe: nothing is added twice.

Request bodyCopy Anchor Link

Unknown fields are rejected.

Consent evidenceCopy Anchor Link

NorthRelay stores the consent source (api for this endpoint), the time, and whatever you pass in consent:

Together these are the record of express consent that CASL (Canada) and GDPR (EU) expect you to be able to produce. Consent is recorded when the contact is created, when it is resubscribed, or when it had no consent record yet; a repeat subscribe does not overwrite earlier evidence. Read it back with Get subscription status.

Example requestCopy Anchor Link

curl -X POST https://app.northrelay.ca/api/v1/subscriptions \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "listIds": ["cmg7l1st00002qz8kfe4w1xyz"],
    "topicIds": ["cmg7t0p1c0003qz8k7h2d4pqr"],
    "doubleOptIn": true,
    "redirectUrl": "https://yourapp.com/newsletter/confirmed",
    "consent": {
      "ip": "203.0.113.24",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6)",
      "text": "Yes, send me the monthly newsletter. I can unsubscribe at any time."
    }
  }'

Example response (201)Copy Anchor Link

{
  "success": true,
  "data": {
    "contactId": "cmg7c0n1t0001qz8k2v5x9abc",
    "email": "jane@example.com",
    "status": "PENDING",
    "created": true,
    "listIds": ["cmg7l1st00002qz8kfe4w1xyz"],
    "addedToListIds": ["cmg7l1st00002qz8kfe4w1xyz"],
    "topicIds": ["cmg7t0p1c0003qz8k7h2d4pqr"],
    "requiresConfirmation": true,
    "confirmationSent": true
  }
}

Webhooks: contact.subscribed (with source: "API"), plus one list.member_added per list in addedToListIds.

Double opt-in flowCopy Anchor Link

1. Your app calls POST /subscriptions with doubleOptIn: true. The contact is PENDING.
2. The recipient receives a confirmation email with a link to https://app.northrelay.ca/c/<token>. The link is valid for 7 days.
3. When they click it, the contact becomes ACTIVE, a contact.confirmed webhook fires, and the recipient is redirected to your redirectUrl (or shown a confirmation page).

List memberships and topic opt-ins are applied immediately, so the contact appears in the list, with status PENDING, as soon as you subscribe it. Campaigns skip PENDING contacts until they confirm.

ErrorsCopy Anchor Link

SDKCopy Anchor Link

TypeScript (@northrelay/sdk 1.9.0). Methods return the response envelope, so the result is in data. Errors are thrown as NorthRelayError with code and fixAction; isSubscriptionError(error, code?) narrows them:

import { NorthRelayClient, isSubscriptionError } from '@northrelay/sdk';

const client = new NorthRelayClient({ apiKey: process.env.NORTHRELAY_API_KEY! });

try {
  const { data } = await client.subscriptions.subscribe({
    email: 'jane@example.com',
    listIds: ['cmg7l1st00002qz8kfe4w1xyz'],
    doubleOptIn: true,
    redirectUrl: 'https://yourapp.com/newsletter/confirmed',
    consent: { ip: req.ip, userAgent: req.headers['user-agent'], text: CONSENT_TEXT },
  });
  console.log(data.status, data.confirmationSent); // 'PENDING', true
} catch (error) {
  if (isSubscriptionError(error, 'RECIPIENT_UNSUBSCRIBED')) {
    // ask for fresh consent, then retry with resubscribe: true
  } else {
    throw error;
  }
}

Python (northrelay 1.9.0, async). The email is positional, the rest are keyword arguments; the result is a SubscribeResult model with snake_case attributes. A 409 raises NorthRelayError with the API code in error.details["code"]:

import os
from northrelay import NorthRelay, NorthRelayError

client = NorthRelay(api_key=os.environ["NORTHRELAY_API_KEY"])

try:
    result = await client.subscriptions.subscribe(
        "jane@example.com",
        list_ids=["cmg7l1st00002qz8kfe4w1xyz"],
        double_opt_in=True,
        redirect_url="https://yourapp.com/newsletter/confirmed",
        consent={"ip": client_ip, "user_agent": user_agent, "text": CONSENT_TEXT},
    )
    print(result.status, result.confirmation_sent)  # PENDING True
except NorthRelayError as error:
    if error.details.get("code") == "RECIPIENT_UNSUBSCRIBED":
        ...  # ask for fresh consent, then retry with resubscribe=True
    else:
        raise

UnsubscribeCopy Anchor Link

Opt an address out from your own server, for example when a user switches off a newsletter in your product's settings.

POST /subscriptions/unsubscribe

Request bodyCopy Anchor Link

What each scope does:

Example requestCopy Anchor Link

curl -X POST https://app.northrelay.ca/api/v1/subscriptions/unsubscribe \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "scope": "topic",
    "topicId": "cmg7t0p1c0003qz8k7h2d4pqr",
    "reason": "Turned off product updates in account settings"
  }'

Example responseCopy Anchor Link

{
  "success": true,
  "data": {
    "email": "jane@example.com",
    "contactId": "cmg7c0n1t0001qz8k2v5x9abc",
    "scope": "topic",
    "changed": true
  }
}

changed is false when the address was already opted out, so the call is safe to repeat. contactId is null when the address is not a contact. A contact.unsubscribed webhook (with method: "api") fires only when something changed, plus list.member_removed for each list the contact left.

ErrorsCopy Anchor Link

SDKCopy Anchor Link

const { data } = await client.subscriptions.unsubscribe({
  email: 'jane@example.com',
  scope: 'topic',
  topicId: 'cmg7t0p1c0003qz8k7h2d4pqr',
});
// data.changed === false when they had already opted out

result = await client.subscriptions.unsubscribe(
    "jane@example.com", scope="topic", topic_id="cmg7t0p1c0003qz8k7h2d4pqr"
)
print(result.changed)

Get subscription statusCopy Anchor Link

Everything you need to render a preference page: the contact and its consent evidence, any account-level suppression, a pending double opt-in, every list membership (current and past) and every topic with a subscribed flag.

GET /subscriptions/{email}

URL-encode the address once (jane%2Bnews%40example.com for jane+news@example.com); do not double-encode it. An address that is not a contact still returns 200 with contact: null, so you can show topic choices before someone subscribes.

Example requestCopy Anchor Link

curl https://app.northrelay.ca/api/v1/subscriptions/jane%40example.com \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example responseCopy Anchor Link

{
  "success": true,
  "data": {
    "email": "jane@example.com",
    "contact": {
      "id": "cmg7c0n1t0001qz8k2v5x9abc",
      "status": "ACTIVE",
      "firstName": "Jane",
      "lastName": null,
      "subscribedAt": "2026-10-06T14:02:11.000Z",
      "unsubscribedAt": null,
      "confirmedAt": "2026-10-06T14:05:40.000Z",
      "consent": {
        "source": "api",
        "at": "2026-10-06T14:02:11.000Z",
        "ip": "203.0.113.24",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6)",
        "text": "Yes, send me the monthly newsletter. I can unsubscribe at any time."
      }
    },
    "suppression": null,
    "unsubscribedFromAll": false,
    "pendingConfirmation": null,
    "lists": [
      {
        "id": "cmg7l1st00002qz8kfe4w1xyz",
        "name": "Monthly newsletter",
        "subscribed": true,
        "addedAt": "2026-10-06T14:02:11.000Z",
        "removedAt": null
      }
    ],
    "topics": [
      {
        "id": "cmg7t0p1c0003qz8k7h2d4pqr",
        "name": "product-updates",
        "label": "Product updates",
        "description": "New features and release notes, about twice a month.",
        "subscribed": true
      }
    ]
  }
}

topics includes topics you have not published on NorthRelay's hosted preference centre; filter them in your page if needed.

ErrorsCopy Anchor Link

SDKCopy Anchor Link

Both SDKs URL-encode the address for you.

const { data: status } = await client.subscriptions.get('jane@example.com');
const optedOut = status.topics.filter((t) => !t.subscribed);

status = await client.subscriptions.get("jane@example.com")
opted_out = [t for t in status.topics if not t.subscribed]
print(status.unsubscribed_from_all, status.contact.consent.text if status.contact else None)

Update preferencesCopy Anchor Link

Apply the choices from your preference page in one call. Returns the updated status in the same shape as Get subscription status.

PATCH /subscriptions/{email}

Request bodyCopy Anchor Link

Provide at least one of topics, lists or unsubscribeAll. Unknown fields are rejected.

Notes:

• Turning a topic back on does not lift a global unsubscribe. To bring back someone who unsubscribed from everything, join a list with resubscribe: true, or call Subscribe with resubscribe: true.
• Changes fire contact.subscribed, contact.unsubscribed, list.member_added and list.member_removed webhooks with method: "api" or source: "API".

Example requestCopy Anchor Link

curl -X PATCH https://app.northrelay.ca/api/v1/subscriptions/jane%40example.com \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "topics": { "cmg7t0p1c0003qz8k7h2d4pqr": false },
    "lists": { "cmg7l1st00002qz8kfe4w1xyz": true }
  }'

The response is the full status object shown under Get subscription status.

ErrorsCopy Anchor Link

SDKCopy Anchor Link

const { data: status } = await client.subscriptions.updatePreferences('jane@example.com', {
  topics: { cmg7t0p1c0003qz8k7h2d4pqr: false },
});

status = await client.subscriptions.update_preferences(
    "jane@example.com",
    topics={"cmg7t0p1c0003qz8k7h2d4pqr": False},
)

Python takes unsubscribe_all=True for unsubscribeAll and raises ValueError before calling the API when none of topics, lists or unsubscribe_all is given.

Resend confirmationCopy Anchor Link

Send the double opt-in email again for a PENDING contact that was subscribed through this API, and move the link's expiry to 7 days from now.

POST /subscriptions/{email}/resend-confirmation

No request body.

Example requestCopy Anchor Link

curl -X POST https://app.northrelay.ca/api/v1/subscriptions/jane%40example.com/resend-confirmation \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Example responseCopy Anchor Link

{
  "success": true,
  "data": {
    "email": "jane@example.com",
    "confirmationSent": true,
    "expiresAt": "2026-10-13T15:10:00.000Z"
  }
}

ErrorsCopy Anchor Link

SDKCopy Anchor Link

const { data } = await client.subscriptions.resendConfirmation('jane@example.com');
console.log(data.expiresAt);

result = await client.subscriptions.resend_confirmation("jane@example.com")
print(result.expires_at)

Neither SDK retries subscribe or resendConfirmation automatically, because a retry could send a second confirmation email.

Unsubscribe linksCopy Anchor Link

Marketing mail from NorthRelay carries a signed, per-recipient unsubscribe token:

• Campaign mail: the {{unsubscribe_url}} template variable, plus List-Unsubscribe and List-Unsubscribe-Post headers (RFC 8058).
• API mail on a marketing message stream: NorthRelay injects the unsubscribe footer and the same headers automatically.

The unsubscribe link has the form https://track.north-pipe.ca/u/{token}. The token identifies your account and the recipient, so the endpoints below need no API key. Unsubscribes from API mail are attributed to your account and fire contact.unsubscribed even when the recipient is not one of your contacts.

Campaign templates can also use {{preferences_url}}, a signed link to NorthRelay's hosted preference centre where the recipient can choose topics or unsubscribe from everything.

Process an unsubscribe from your own pageCopy Anchor Link

If you host your own unsubscribe landing page, send the token and the recipient's choice here. This endpoint is public; the token is the authentication.

POST /unsubscribe

curl -X POST https://app.northrelay.ca/api/v1/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{ "token": "<token from the unsubscribe link>", "scope": "all" }'

{
  "success": true,
  "message": "Successfully unsubscribed from all marketing emails",
  "data": { "scope": "all", "changed": true }
}

A bare contactId is no longer accepted: it let anyone who learned a contact id opt that person out. For opt-outs from your own server use POST /subscriptions/unsubscribe with your API key.

One-click unsubscribe (RFC 8058)Copy Anchor Link

POST /unsubscribe/one-click?token={token}

Mailbox providers (Gmail, Yahoo, Outlook) call the one-click URL from the List-Unsubscribe header when the recipient presses their built-in "Unsubscribe" button; NorthRelay's tracking service forwards those requests here. It unsubscribes the recipient from all marketing mail (webhook method: "one_click") and always answers 200, as RFC 8058 requires, even when the token cannot be resolved. A missing token returns 400.

GET /unsubscribe/one-click?token= does not unsubscribe. Link scanners and security gateways prefetch URLs, so a GET redirects (303) to the confirmation page, where the recipient presses a button.

RelatedCopy Anchor Link

• Mailing Lists guide: build signup, double opt-in and a preference page end to end
• Contacts API: contacts, lists, members, CSV import
• Suppressions API: topics (suppression groups) and account-level suppressions
• Webhooks: contact.*, list.*, email.opened, email.clicked