Messages

Send a message

Send a real email — the one send door for all outbound mail. `from` is a sender id (snd_…) or any address on a provisioned sending domain (e.g. "[email protected]" or "Acme <[email protected]>"; the identity is created on first use). Provide content inline (subject + html/text) or render a stored template with variantId + data. Reply to an inbound message by passing inReplyTo (the send threads to that conversation); set test:true for a one-off preview that is excluded from campaign stats. For a paced (cold) sender, pass sequence to enroll the person instead of sending now.

POST

messages

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.messages.create({ from: "snd_y3rgwmhkbgxxa2qzmfyrdj0e", to: "[email protected]", sequence: "prg_y3rgwmhkbgxxa2qzmfyrdj0e" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "contactEmail": "[email protected]",
  "contactName": "<string>",
  "id": "act_y3rgwmhkbgxxa2qzmfyrdj0e",
  "personId": "con_mfyrdj0ey3rgwmhkbgxxa2qz",
  "senderId": "snd_y3rgwmhkbgxxa2qzmfyrdj0e",
  "subject": "Quick question, Ada",
  "threadId": "<string>",
  "channel": "email",
  "direction": "outbound",
  "failureCode": "dlq_exhausted",
  "isTest": true,
  "programId": "prg_a2qzmfyrdj0ey3rgwmhkbgxx",
  "status": "sent",
  "stepId": "stp_mfyrdj0ey3rgwmhkbgxxa2qz",
  "object": "message",
  "occurredAt": "2026-06-10T15:04:05.000Z"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Org-scoped Norbelys API key. Create one in Settings → API keys and send it as Authorization: Bearer ak_….

Headers

Idempotency-Key

string

Opt-in idempotency for a safely retried write: reuse the same key to replay the original result for 24h instead of re-executing. Recommended on every POST.

Maximum string length: 255

Body

application/json

MessageEnrollParams
MessageReplyParams
MessageTestParams

from

string

required

Who the message is sent from — a sender id, or any email address on a sending domain you've set up (a sender identity is created automatically on first use).

Examples:

"snd_y3rgwmhkbgxxa2qzmfyrdj0e"

"[email protected]"

"Acme <[email protected]>"

string<email>

required

Recipient email address.

Example:

"[email protected]"

sequence

string

required

Id of a program to enroll the person into instead of sending now; the program then controls send timing. Required for a cold-email sender (those send on a paced schedule, not immediately).

Example:

"prg_y3rgwmhkbgxxa2qzmfyrdj0e"

data

object

Template variables merged over the person's fields at render time.

Show child attributes

Example:

{ "orderId": "ORD-1042" }

toName

string

Recipient display name.

Example:

"Ada Lovelace"

Response

OutboundMessage
InboundMessage

contactEmail

string | null

required

The other party's email — the recipient on outbound, the sender on inbound.

Example:

"[email protected]"

contactName

string | null

required

The other party's name.

string

required

The message id.

Example:

"act_y3rgwmhkbgxxa2qzmfyrdj0e"

personId

string | null

required

The linked person, if any.

Example:

"con_mfyrdj0ey3rgwmhkbgxxa2qz"

senderId

string | null

required

The mailbox involved, if any.

Example:

"snd_y3rgwmhkbgxxa2qzmfyrdj0e"

subject

string | null

required

The message subject.

Example:

"Quick question, Ada"

threadId

string | null

required

RFC conversation thread id.

channel

enum<string>

required

Outbound channel: email, call, sms, or linkedin.

Available options:

email,

call,

sms,

linkedin

Example:

"email"

direction

any

required

Message direction — an outbound send.

failureCode

string | null

required

Machine-readable delivery failure or bounce reason; null when none was recorded. Inspect this when status is failed or bounced.

Example:

"dlq_exhausted"

isTest

boolean

required

A test/probe send — surfaced in the log but excluded from campaign rates.

programId

string | null

required

The campaign this message belongs to, when any; null for one-off/test sends.

Example:

"prg_a2qzmfyrdj0ey3rgwmhkbgxx"

status

enum<string>

required

Delivery status: queued, sent, delivered, failed, bounced, or cancelled.

Available options:

queued,

sent,

delivered,

failed,

bounced,

cancelled

Example:

"sent"

stepId

string | null

required

The cadence step that produced this send, when any; null for one-off sends.

Example:

"stp_mfyrdj0ey3rgwmhkbgxxa2qz"

object

any

default:message

Always "message" — identifies the resource type.

occurredAt

any

Send/receive instant (RFC 3339).

Example:

"2026-06-10T15:04:05.000Z"

import { createClient } from "@norbelys/sdk";

const norbelys = createClient({ apiKey: process.env.NORBELYS_API_KEY });

const { data, error } = await norbelys.messages.create({ from: "snd_y3rgwmhkbgxxa2qzmfyrdj0e", to: "[email protected]", sequence: "prg_y3rgwmhkbgxxa2qzmfyrdj0e" });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "contactEmail": "[email protected]",
  "contactName": "<string>",
  "id": "act_y3rgwmhkbgxxa2qzmfyrdj0e",
  "personId": "con_mfyrdj0ey3rgwmhkbgxxa2qz",
  "senderId": "snd_y3rgwmhkbgxxa2qzmfyrdj0e",
  "subject": "Quick question, Ada",
  "threadId": "<string>",
  "channel": "email",
  "direction": "outbound",
  "failureCode": "dlq_exhausted",
  "isTest": true,
  "programId": "prg_a2qzmfyrdj0ey3rgwmhkbgxx",
  "status": "sent",
  "stepId": "stp_mfyrdj0ey3rgwmhkbgxxa2qz",
  "object": "message",
  "occurredAt": "2026-06-10T15:04:05.000Z"
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

{
  "error": {
    "code": "invalid_param",
    "message": "<string>",
    "type": "invalid_request",
    "doc_url": "<string>",
    "hint": "<string>"
  }
}

Analytics

Domains

Fields

Files

Groups

Integrations

Messages

Organization

People

Programs

Segments

Senders

Suppressions

Verify

Send a message

Authorizations

Headers

Body

Response