Send single emails, batch emails, scheduled emails, and validate email addresses via the NorthRelay API.

Sending API

The Sending API provides four endpoints for email delivery and address validation. Contact support to confirm SMTP/IMAP availability for your account.

Each message supports at most 100 distinct recipients across To, CC and BCC. Addresses are deduplicated before quota accounting. Quota reserves recipient attempts at acceptance; a downstream rejection does not automatically refund the reservation. Queued retries reuse the reservation. Account and platform daily limits also apply. Hard-bounced and complained recipients are excluded from every envelope field; marketing mail also honors opt-outs.

Sending requests are limited to 8 MiB of JSON; each HTML/text body is limited to 1 MiB. Ambiguous submission outcomes are held for review to prevent duplicate delivery. Check message status before submitting a replacement request.

Send Email

Send a single email to one or more recipients.

POST /emails/send

Request Body

Field	Type	Required	Description
`from`	EmailAddress	Yes	Sender address
`to`	EmailAddress[]	Yes	Recipients (1--100, shared total with CC/BCC)
`cc`	EmailAddress[]	No	CC recipients
`bcc`	EmailAddress[]	No	BCC recipients
`replyTo`	EmailAddress	No	Reply-to address
`content`	Content	Yes	Email content (subject, body, or template)
`variables`	Record<string, string>	No	Template variables for `{{variable}}` substitution
`themeId`	string	No	Theme ID for styled rendering
`categories`	string[]	No	Up to 10 categories (alphanumeric, hyphens, underscores; max 64 chars each)
`tags`	Record<string, string>	No	Custom key-value tags for filtering in analytics
`metadata`	Record<string, any>	No	Arbitrary metadata returned in webhooks
`attachments`	Attachment[]	No	File attachments

Example Request

curl -X POST https://app.northrelay.ca/api/v1/emails/send \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "hello@yourdomain.com", "name": "Acme Inc" },
    "to": [
      { "email": "alice@example.com", "name": "Alice" }
    ],
    "replyTo": { "email": "support@yourdomain.com" },
    "content": {
      "subject": "Your order has shipped",
      "html": "<h1>Order #1234</h1><p>Your package is on the way.</p>",
      "text": "Order #1234 - Your package is on the way."
    },
    "categories": ["transactional", "order-updates"],
    "tags": { "order_id": "1234" },
    "metadata": { "internal_ref": "ship-batch-42" }
  }'

Example Response

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "queued",
  "from": "hello@yourdomain.com",
  "to": ["alice@example.com"],
  "subject": "Your order has shipped",
  "createdAt": "2026-03-19T14:30:00.000Z"
}

Batch Send

Send personalized emails to up to 1,000 recipients in a single request. Each recipient can have unique variable substitutions.

POST /emails/batch

Request Body

Field	Type	Required	Description
`from`	EmailAddress	Yes	Sender address (shared across all recipients)
`recipients`	BatchRecipient[]	Yes	Recipients with per-recipient variables (1--1,000)
`content`	Content	Yes	Shared email content; `subject` is required (not optional)
`categories`	string[]	No	Up to 10 categories
`tags`	Record<string, string>	No	Custom key-value tags
`metadata`	Record<string, any>	No	Arbitrary metadata

BatchRecipient Object

Field	Type	Required	Description
`to`	EmailAddress	Yes	Recipient address
`cc`	EmailAddress[]	No	CC recipients for this message
`bcc`	EmailAddress[]	No	BCC recipients for this message
`variables`	Record<string, string>	No	Per-recipient template variables

Example Request

curl -X POST https://app.northrelay.ca/api/v1/emails/batch \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "hello@yourdomain.com", "name": "Acme Inc" },
    "recipients": [
      {
        "to": { "email": "alice@example.com", "name": "Alice" },
        "variables": { "first_name": "Alice", "plan": "Startup" }
      },
      {
        "to": { "email": "bob@example.com", "name": "Bob" },
        "variables": { "first_name": "Bob", "plan": "Scale" }
      }
    ],
    "content": {
      "subject": "Welcome to {{plan}}, {{first_name}}!",
      "html": "<h1>Hi {{first_name}}</h1><p>You are now on the {{plan}} plan.</p>"
    },
    "categories": ["onboarding"]
  }'

Example Response

{
  "batchId": "batch_x1y2z3",
  "status": "queued",
  "totalRecipients": 2,
  "createdAt": "2026-03-19T14:30:00.000Z"
}

Schedule Email

Schedule an email for future delivery. The request body is identical to Send Email with one additional required field.

POST /emails/schedule

Additional Field

Field	Type	Required	Description
`scheduledFor`	string (ISO 8601)	Yes	Delivery time; must be in the future and within 1 year

Example Request

curl -X POST https://app.northrelay.ca/api/v1/emails/schedule \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "hello@yourdomain.com" },
    "to": [{ "email": "alice@example.com" }],
    "content": {
      "subject": "Your trial ends tomorrow",
      "html": "<p>Just a reminder that your trial expires on March 20.</p>"
    },
    "scheduledFor": "2026-03-20T09:00:00.000Z"
  }'

Example Response

{
  "id": "msg_s4c5h6e7d8",
  "status": "scheduled",
  "scheduledFor": "2026-03-20T09:00:00.000Z",
  "createdAt": "2026-03-19T14:30:00.000Z"
}

Cancelling a Scheduled Email

DELETE /emails/schedule/{id}

Cancel a scheduled email before it is sent. Returns 404 if the email has already been delivered.

curl -X DELETE https://app.northrelay.ca/api/v1/emails/schedule/msg_s4c5h6e7d8 \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx"

Validate Email

Check whether an email address is deliverable without sending a message. Performs syntax validation, DNS MX lookup, and optionally SMTP handshake verification.

POST /emails/validate

Request Body

Field	Type	Required	Default	Description
`email`	string	Yes	--	Email address to validate
`extended`	boolean	No	`false`	Enable SMTP handshake check (slower but more accurate)
`timeout`	integer	No	`10000`	Timeout in milliseconds (1,000--60,000)

Example Request

curl -X POST https://app.northrelay.ca/api/v1/emails/validate \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "extended": true,
    "timeout": 15000
  }'

Example Response

{
  "email": "alice@example.com",
  "valid": true,
  "checks": {
    "syntax": true,
    "mxRecords": true,
    "smtpHandshake": true,
    "disposable": false,
    "roleAccount": false
  },
  "suggestion": null
}

When validation fails, the suggestion field may offer a corrected address (e.g., "suggestion": "alice@gmail.com" for a misspelled domain).

Bulk Validate

Validate up to 10,000 addresses in a single request.

POST /emails/validate/bulk

Field	Type	Required	Default	Description
`emails`	string[]	Yes	--	Email addresses to validate (1--10,000)
`extended`	boolean	No	`false`	Enable SMTP handshake checks
`timeout`	integer	No	`30000`	Timeout in milliseconds (1,000--60,000)
`continueOnError`	boolean	No	`true`	Continue validating remaining addresses if one fails

Shared Types

EmailAddress

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`name`	string	No	Display name

{ "email": "alice@example.com", "name": "Alice Johnson" }

Content

Field	Type	Required	Description
`subject`	string	Conditional	Required unless `templateId` is provided (1--998 chars)
`html`	string	Conditional	HTML body; at least one of `html`, `text`, or `templateId` is required
`text`	string	Conditional	Plain-text body
`templateId`	string	Conditional	ID of a Studio template; the send uses its live release
`attachments`	Attachment[]	No	File attachments

Attachment

Field	Type	Required	Description
`filename`	string	Yes	File name with extension (e.g., `invoice.pdf`)
`content`	string	Yes	Base64-encoded file content
`contentType`	string	Yes	MIME type (e.g., `application/pdf`)

Validation Rules Summary

Constraint	Value
Max recipients per send	1,000
Max recipients per batch	1,000
Max subject length	998 characters
Max categories per email	10
Category format	Alphanumeric, hyphens, underscores; max 64 chars
Schedule window	Must be in the future, within 1 year
Max bulk validate addresses	10,000
Validate timeout range	1,000--60,000 ms

Sending API

Sending APICopy Anchor Link

Send EmailCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Batch SendCopy Anchor Link

Request BodyCopy Anchor Link

BatchRecipient ObjectCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Schedule EmailCopy Anchor Link

Additional FieldCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Cancelling a Scheduled EmailCopy Anchor Link

Validate EmailCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Bulk ValidateCopy Anchor Link

Shared TypesCopy Anchor Link

EmailAddressCopy Anchor Link

ContentCopy Anchor Link

AttachmentCopy Anchor Link

Validation Rules SummaryCopy Anchor Link

On this page

Sending API

Send Email

Request Body

Example Request

Example Response

Batch Send

Request Body

BatchRecipient Object

Example Request

Example Response

Schedule Email

Additional Field

Example Request

Example Response

Cancelling a Scheduled Email

Validate Email

Request Body

Example Request

Example Response

Bulk Validate

Shared Types

EmailAddress

Content

Attachment

Validation Rules Summary