Skip to content
Norbelys
Esc
↑↓navigate↵open⌘Jpreview

Create a connection. A credential-based one (SMTP, a relay, the managed MTA) is created in `verifying`, or the workspace's archived connection of the same account comes back with its id, history and identities; a check (or the managed MTA's provisioning) proves it. A Google or Microsoft mailbox answers `202` with the consent URL; the callback creates it.

POST/v1/connections
Authorization
AuthorizationBearer token · headerrequired

An API key (nb_live_…, nb_test_…), a workspace token (nbs_…) or a CLI token (nbc_…).

Header parameters
Idempotency-Keystringrequired

A stable key for this logical request; reuse it when retrying.

min length 1 · max length 128 · matches ^[!-~]+$
Request body
requiredapplication/json
account_emailstring | null

The account (not for Google and Microsoft, whose address the provider names): an SMTP login, the From address of a paced SES connection or of the managed MTA, a name for a relay account.

daily_limitinteger<int32> | null

Submissions a UTC day.

identitiesIdentityInput[] | null

The From addresses, at most 50; by default the account's own address.

Show properties
Array of IdentityInput
emailstring<email>required

The From address.

enabledboolean | null

Whether campaigns may send from it (default true).

idstring | null

The identity to update (sid_…); absent for a new one.

namestring | null

The display name, 1 to 200 characters.

reply_tostring<email> | null

The Reply-To address.

signature_htmlstring | null

The HTML signature, at most 64 KiB.

signature_textstring | null

The text signature, at most 64 KiB.

tagsstring[] | null

Up to 20 tags of 1 to 64 characters.

verifiedboolean | null

The person attests the address may be sent as (default false); a Gmail mailbox's check replaces it with what Gmail says.

imapImapInput | null
Show properties
One of:
ImapInput
hoststringrequired

The host name.

portinteger<int32>required

The port.

min 0
securityImapSecurityrequired

How an IMAP session is secured.

Allowed:tlsplain
null
null
providerProviderrequired

The provider behind a connection (connections.provider).

Allowed:smtpgooglemicrosoftsessendgridmailgunnorbelys
quota_scope_idstring | null

The quota scope of the account; required for SES.

receivingReceivingInput | null
Show properties
One of:
ReceivingInput
foldersstring[]required

Folder names at the provider, at most 10; INBOX is the inbox.

null
null
return_tostring | null

Google and Microsoft: the dashboard path the browser returns to after the consent.

send_interval_minutesinteger<int32> | null

A paced sender's minutes between cold sends, 5 to 1,440, rounded up to whole 5-minute slots; 10 for a mailbox when absent; on SES it makes the connection a paced sender of one From address; refused for SendGrid, Mailgun and the managed MTA.

send_windowSendWindow | null
Show properties
One of:
SendWindow
daysinteger<int32>[]required

The days of the week, 1 (Monday) to 7 (Sunday), each once, in order.

endstringrequired

The closing time, HH:MM, after the opening; 24:00 closes at midnight.

startstringrequired

The opening time, HH:MM.

null
null
smtpSmtpInput | null
Show properties
One of:
SmtpInput
configuration_setstring | null

Amazon SES: the configuration set every message names.

hoststringrequired

The host name.

passwordstringrequired

The password, app password or relay key.

portinteger<int32>required

The port.

min 0
securitySecurityrequired

How an SMTP session is secured.

Allowed:tlsstarttlsplain
usernamestring | null

The login; an SMTP login's is its account (account_email).

null
null
timezonestring | null

The send window's IANA time zone (UTC by default).

warmup_stageinteger<int32> | null

The warm-up stage to start at; absent when not warming.

webhookWebhookInput | null
Show properties
One of:
WebhookInput
keystringrequired

Mailgun: the HTTP webhook signing key. SendGrid: the verification key its webhook shows (base64). SES: the ARN of the SNS topic the configuration set posts to.

null
null
Responses
201

The connection, verifying.

accountAccountrequired

The account behind a connection.

Show properties
emailstringrequired

The mailbox's address, an SMTP login as it is, the From address a paced SES connection paces, or a name the customer gave a relay account.

issuerstring | null

For OAuth: the ID token's issuer.

subjectstring | null

For OAuth: the provider's immutable subject, kept through address changes and archive.

authorizationAuthorization | null
Show properties
One of:
Authorization
expires_atTimestamprequired

When the ceremony expires.

urlstringrequired

The provider's consent page.

null
null
checked_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
created_atTimestamprequired
created_bystring | null
daily_limitinteger<int32>required

Submissions a UTC day.

idId_Connectionrequired
matches ^con_[0-9a-f]{32}$
identitiesIdentityObject[]required

The From addresses, at most 50.

max items 50
Show properties
Array of IdentityObject
created_atTimestamprequired
emailstringrequired

The From address.

enabledbooleanrequired

Whether campaigns may send from it.

idId_SenderIdentityrequired
matches ^sid_[0-9a-f]{32}$
namestring | null

The display name.

reply_tostring | null

The Reply-To address.

signature_htmlstring | null

The signature appended to HTML bodies.

signature_textstring | null

The signature appended to text bodies.

tagsstring[]required

Tags a campaign selects senders by.

updated_atTimestamprequired
verifiedbooleanrequired

Whether the address may be sent as: confirmed by the provider where it can say, else the person's word.

imapImapSettings | null
Show properties
One of:
ImapSettings
hoststringrequired

The host name.

portinteger<int32>required

The port.

min 0
securityImapSecurityrequired

How an IMAP session is secured.

Allowed:tlsplain
null
null
pausedbooleanrequired

The person's pause: sending stops, conversations wait.

paused_untilTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
providerstringrequired

smtp, google, microsoft, ses, sendgrid, mailgun or norbelys; new values may be added.

quota_scope_idstring | null
receivingReceivingObjectrequired

What a connection reads, as the API shows it.

Show properties
foldersFolderObject[]required

The folders, oldest first; a disabled one is no longer read. Every enabled folder is shown, and disabled ones while there is room.

max items 10
Show properties
Array of FolderObject
enabledbooleanrequired

Whether it is read.

failuresinteger<int32>required

Consecutive failed reads.

folderstringrequired

The folder's name at the provider (INBOX).

idId_ReceiveBindingrequired
matches ^rcv_[0-9a-f]{32}$
polled_atTimestamp | null
Show properties
One of:
Timestamp
Timestamp
null
null
status_detailstring | null

What the last failed read said.

send_interval_minutesinteger<int32> | null

A paced sender's minutes between cold sends, whole 5-minute slots; null when rate-paced.

send_windowSendWindow | null
Show properties
One of:
SendWindow
daysinteger<int32>[]required

The days of the week, 1 (Monday) to 7 (Sunday), each once, in order.

endstringrequired

The closing time, HH:MM, after the opening; 24:00 closes at midnight.

startstringrequired

The opening time, HH:MM.

null
null
smtpSmtpSettings | null
Show properties
One of:
SmtpSettings
configuration_setstring | null

The Amazon SES configuration set every message names, so SES publishes its events.

hoststringrequired

The host name.

portinteger<int32>required

The port.

min 0
securitySecurityrequired

How an SMTP session is secured.

Allowed:tlsstarttlsplain
usernamestringrequired

The login.

null
null
statusstringrequired

verifying, active, authorization_required, failed, disabled or archived; new values may be added.

status_detailstring | null

The health text: what went wrong and what to do.

timezonestringrequired

The IANA time zone of the send window.

transportstringrequired

smtp or api.

updated_atTimestamprequired
usageUsagerequired

The daily budget's use today and yesterday (UTC days).

Show properties
todayUsageDayrequired

A day's use of the daily budget.

Show properties
reservedinteger<int32>required

Submissions claimed and not settled yet.

usedinteger<int32>required

Submissions the provider accepted (or may have).

yesterdayUsageDayrequired

A day's use of the daily budget.

Show properties
reservedinteger<int32>required

Submissions claimed and not settled yet.

usedinteger<int32>required

Submissions the provider accepted (or may have).

versioninteger<int64>required

The connection's version, also the response's ETag: updated_at in microseconds since the Unix epoch. An update sent with it in If-Match applies only to this version, so a replacement of identities or of the folders read never undoes a change made since it was read. Health checks and the sender's pacing move it too.

warmup_stageinteger<int32> | null

The warm-up stage; null when not warming.

webhookWebhookObject | null
Show properties
One of:
WebhookObject
idId_ProviderWebhookrequired
matches ^pwh_[0-9a-f]{32}$
key_setbooleanrequired

Whether its verification material is set: SendGrid's verification key, Mailgun's signing key, the SNS topic for SES; callbacks are refused until it is.

urlstringrequired

The URL to configure at the provider (an SES connection's quota scope names the one its account subscribes).

null
null
202

Google or Microsoft: the consent to open, with the ceremony cookie.

authorizationAuthorizationrequired

A consent the browser must give: open url, from the browser that received the ceremony cookie with this answer.

Show properties
expires_atTimestamprequired

When the ceremony expires.

urlstringrequired

The provider's consent page.

401

No valid credential.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

403

The credential lacks connections:manage.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

404

No such quota scope in this workspace.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

409

The account is connected already (conflict), naming the live connection.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

422

The body is invalid.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.norbelys.com/v1/connections' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "account_email": "ada@example.com",
  "daily_limit": 50,
  "imap": {
    "host": "imap.example.com",
    "port": 993,
    "security": "tls"
  },
  "provider": "smtp",
  "send_interval_minutes": 10,
  "smtp": {
    "host": "smtp.example.com",
    "password": "app-password",
    "port": 587,
    "security": "starttls"
  }
}'
Response
{
  "account": {
    "email": "string",
    "issuer": "string",
    "subject": "string"
  },
  "authorization": {
    "expires_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "checked_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "string",
  "daily_limit": 0,
  "id": "con_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "identities": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "email": "string",
      "enabled": true,
      "id": "sid_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
      "name": "string",
      "reply_to": "string",
      "signature_html": "string",
      "signature_text": "string",
      "tags": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "verified": true
    }
  ],
  "imap": {
    "host": "string",
    "port": 0,
    "security": "tls"
  },
  "paused": true,
  "paused_until": "2019-08-24T14:15:22Z",
  "provider": "string",
  "quota_scope_id": "string",
  "receiving": {
    "folders": [
      {
        "enabled": true,
        "failures": 0,
        "folder": "string",
        "id": "rcv_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
        "polled_at": "2019-08-24T14:15:22Z",
        "status_detail": "string"
      }
    ]
  },
  "send_interval_minutes": 0,
  "send_window": {
    "days": [
      0
    ],
    "end": "string",
    "start": "string"
  },
  "smtp": {
    "configuration_set": "string",
    "host": "string",
    "port": 0,
    "security": "tls",
    "username": "string"
  },
  "status": "string",
  "status_detail": "string",
  "timezone": "string",
  "transport": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage": {
    "today": {
      "reserved": 0,
      "used": 0
    },
    "yesterday": {
      "reserved": 0,
      "used": 0
    }
  },
  "version": 0,
  "warmup_stage": 0,
  "webhook": {
    "id": "pwh_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
    "key_set": true,
    "url": "string"
  }
}