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

Verify a connection now: it becomes `verifying` and its check runs (the managed MTA's provisioning, for a `norbelys` connection). For an OAuth connection whose grant is lost, the answer carries `authorization.url` for the browser instead, and the ceremony cookie.

POST/v1/connections/{id}/verify
Authorization
AuthorizationBearer token · headerrequired

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

Path parameters
idId_Connectionrequired

The connection id (con_…).

matches ^con_[0-9a-f]{32}$
Query parameters
return_tostring

OAuth: the dashboard path the browser returns to after the consent.

Header parameters
Idempotency-Keystringrequired

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

min length 1 · max length 128 · matches ^[!-~]+$
Responses
200

The connection, verifying, or with authorization when consent is needed.

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
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, or a member does not own the 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.

404

No such connection 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 connection is archived (invalid_state).

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 return path 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
Request
curl -X POST 'https://api.norbelys.com/v1/connections/con_0190f8a2b4c87a10b6d2e4f6a8c0e2f4/verify' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string'
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"
  }
}