Connect a sender

POST

senders

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

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

const { data, error } = await norbelys.senders.create({ fromEmail: "[email protected]", fromName: "Ada from Acme", smtp: { host: "smtp.gmail.com", port: 465 }, transportMode: null });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "bccCrmEmail": "[email protected]",
  "clientLabel": "Acme Corp",
  "dailyLimit": 50,
  "fromEmail": "[email protected]",
  "fromName": "Ada from Acme",
  "id": "snd_pfh0haxfpzowht3oi213cqos",
  "imapHost": "imap.gmail.com",
  "imapPort": 993,
  "imapSecurity": "ssl",
  "minGapMinutes": 5,
  "replyTo": "[email protected]",
  "reputation": "good",
  "sendingDomainId": "dom_tz4a98xat96iws9zmbrgj3a",
  "signatureHtml": "<string>",
  "smtpHost": "smtp.gmail.com",
  "smtpPort": 465,
  "smtpSecurity": "ssl",
  "state": "healthy",
  "tags": [
    "acme-pool",
    "us"
  ],
  "transportMode": "smtp",
  "transportProvider": "google",
  "archivedAt": "<unknown>",
  "createdAt": "<unknown>",
  "healthUpdatedAt": "<unknown>",
  "object": "sender",
  "updatedAt": "<unknown>"
}

{
  "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

SmtpSenderInput
ProviderApiSenderInput
SelfHostedSenderInput
VoiceSenderInput

fromEmail

string

required

The sending address.

Minimum string length: 1

Example:

"[email protected]"

fromName

string

required

Display name.

Example:

"Ada from Acme"

smtp

SmtpConnectionSettings · object

required

SMTP server and credentials the mail is sent through.

Show child attributes

transportMode

any

required

Send over SMTP from this mailbox's own server.

bccCrmEmail

string<email>

BCC every send to this address (CRM capture).

Example:

"[email protected]"

clientLabel

string

Free-text label for this mailbox (e.g. to tag by client).

Example:

"Acme Corp"

dailyLimit

integer

Maximum sends per day for this mailbox.

Required range: x >= 0

Example:

50

minGapMinutes

integer

Minimum gap between sends from this mailbox (floor 3; server default 5).

Required range: x >= 3

Example:

5

replyTo

string<email>

Reply-To override.

Example:

"[email protected]"

sendingDomainId

string

The sending domain id. Omit to get-or-create it from the fromEmail host.

Example:

"dom_tz4a98xat96iws9zmbrgj3a"

signatureHtml

string

HTML signature appended to every send.

Response

bccCrmEmail

string<email> | null

required

BCC every send to this address (CRM capture).

Example:

"[email protected]"

clientLabel

string | null

required

Free-text label for this mailbox (e.g. to tag by client).

Example:

"Acme Corp"

dailyLimit

integer

required

Max sends per day for this mailbox.

Required range: x >= 0

Example:

50

fromEmail

string<email>

required

The sending address.

Example:

"[email protected]"

fromName

string

required

Display name.

Example:

"Ada from Acme"

string

required

The sender id.

Example:

"snd_pfh0haxfpzowht3oi213cqos"

imapHost

string | null

required

The IMAP server host.

Example:

"imap.gmail.com"

imapPort

integer | null

required

The IMAP server port.

Required range: 1 <= x <= 65535

Example:

993

imapSecurity

enum<string> | null

required

IMAP TLS mode: ssl (implicit TLS), tls (STARTTLS), or none.

Available options:

ssl,

tls,

none

Example:

"ssl"

minGapMinutes

integer

required

Minimum gap between sends from this mailbox.

Required range: x >= 0

Example:

5

replyTo

string<email> | null

required

Reply-To override.

Example:

"[email protected]"

reputation

enum<string>

required

System-computed reputation tier: good, warning, or bad.

Available options:

good,

warning,

bad

Example:

"good"

sendingDomainId

string

required

The sending domain this mailbox lives under.

Example:

"dom_tz4a98xat96iws9zmbrgj3a"

signatureHtml

string | null

required

HTML signature appended to every send.

smtpHost

string | null

required

The SMTP server host.

Example:

"smtp.gmail.com"

smtpPort

integer | null

required

The SMTP server port.

Required range: 1 <= x <= 65535

Example:

465

smtpSecurity

enum<string> | null

required

SMTP TLS mode: ssl (implicit TLS), tls (STARTTLS), or none.

Available options:

ssl,

tls,

none

Example:

"ssl"

state

enum<string>

required

Operational state: healthy, throttled, or paused.

Available options:

healthy,

throttled,

paused

Example:

"healthy"

tags

string[]

required

Free-form tags on this mailbox. A campaign whose senderTags selector names any of them auto-attaches (and auto-detaches) the mailbox — tag a fleet once and campaigns pick it up dynamically.

Example:

["acme-pool", "us"]

transportMode

enum<string>

required

How messages are carried: smtp, provider_api, self_hosted, or voice.

Available options:

smtp,

provider_api,

self_hosted,

voice

Example:

"smtp"

transportProvider

string | null

required

Managed provider, if any; null for a plain cold/SMTP mailbox.

Example:

"google"

archivedAt

any

When this mailbox was archived (soft-deleted), or null if active.

createdAt

any

When this mailbox was created (RFC 3339).

healthUpdatedAt

any

When this mailbox's health was last updated (RFC 3339), or null.

object

any

default:sender

Always "sender". Identifies the object type.

updatedAt

any

When this mailbox was last updated (RFC 3339).

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

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

const { data, error } = await norbelys.senders.create({ fromEmail: "[email protected]", fromName: "Ada from Acme", smtp: { host: "smtp.gmail.com", port: 465 }, transportMode: null });
if (error) {
  throw new Error(error.error.message);
}
console.log(data);

{
  "bccCrmEmail": "[email protected]",
  "clientLabel": "Acme Corp",
  "dailyLimit": 50,
  "fromEmail": "[email protected]",
  "fromName": "Ada from Acme",
  "id": "snd_pfh0haxfpzowht3oi213cqos",
  "imapHost": "imap.gmail.com",
  "imapPort": 993,
  "imapSecurity": "ssl",
  "minGapMinutes": 5,
  "replyTo": "[email protected]",
  "reputation": "good",
  "sendingDomainId": "dom_tz4a98xat96iws9zmbrgj3a",
  "signatureHtml": "<string>",
  "smtpHost": "smtp.gmail.com",
  "smtpPort": 465,
  "smtpSecurity": "ssl",
  "state": "healthy",
  "tags": [
    "acme-pool",
    "us"
  ],
  "transportMode": "smtp",
  "transportProvider": "google",
  "archivedAt": "<unknown>",
  "createdAt": "<unknown>",
  "healthUpdatedAt": "<unknown>",
  "object": "sender",
  "updatedAt": "<unknown>"
}

{
  "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

Authorizations

Headers

Body

Response