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

Update a connection: pause or resume it, change its pacing, identities or folders, or give it a new credential (then it is verified again).

PATCH/v1/connections/{id}
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}$
Header parameters
If-Matchstring

The version the change applies to, quoted as the ETag that carried it ("1790000000000000"), or *. A version that is no longer current answers 412 precondition_failed and changes nothing; without the header the change applies to whatever version is current.

Idempotency-Keystring

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

min length 1 · max length 128 · matches ^[!-~]+$
Request body
requiredapplication/json
api_credentialApiCredentialInput | null
Show properties
One of:
ApiCredentialInput
idstring | null

Amazon SES: the AWS access key id (AKIA…); absent for SendGrid and Mailgun.

secretstringrequired

The AWS secret access key, or the SendGrid or Mailgun API key.

null
null
daily_limitinteger<int32> | null
identitiesIdentityInput[] | null

The whole list of identities: one with its id is replaced, one without is added, one left out is removed (one with history is kept: disable it instead).

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
pausedboolean | null

Pause or resume sending.

quota_scope_idstring | null

Another quota scope, or null (not 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
send_interval_minutesinteger<int32> | null

A paced sender's new interval, rounded up to whole 5-minute slots; a rate-paced connection takes none.

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
smtpSmtpPatch | null
Show properties
One of:
SmtpPatch
configuration_setstring | null
hoststring | null
passwordstring | null

A new password: the connection is verified again.

portinteger<int32> | null
min 0
securitySecurity | null
Show properties
One of:
Security
string
null
null
usernamestring | null
null
null
timezonestring | null
warmup_stageinteger<int32> | null
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
200

The connection.

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
400

The body is not JSON, or If-Match is malformed (invalid_request).

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.

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), or an identity's address belongs to another connection (conflict).

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.

412

If-Match names a version that is no longer current (precondition_failed); nothing changed.

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 PATCH 'https://api.norbelys.com/v1/connections/con_0190f8a2b4c87a10b6d2e4f6a8c0e2f4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "paused": true
}'
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"
  }
}