Suppress an address, or a list of them: no mail of the workspace reaches them any more.

Two forms. email suppresses one address and answers the suppression (201), or 409 when it is suppressed already. emails suppresses up to 1,000 addresses as one decision and answers what it did (200): how many it suppressed, how many were suppressed already, and each entry that is not an address. Either way the reason is manual, and every live enrollment of an address suppressed now stops in the same transaction.

POST/v1/suppressions

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

One of:

CreateSuppression

emailstring<email>required

The address to stop mailing.

reasonSuppressionReason | null

Show properties

One of:

SuppressionReason

string

null

null

CreateSuppressions

emailsstring[]required

1 to 1,000 addresses to stop mailing. Each entry is read on its own: one that is not an address is reported in invalid and the others are suppressed; an address given twice, in any case, counts once.

min items 1 · max items 1000

reasonSuppressionReason | null

Show properties

One of:

SuppressionReason

string

null

null

Responses

200

For emails: what the request did.

alreadyintegerrequired

Addresses that were suppressed before this request, for any reason; they stay as they were.

min 0

createdintegerrequired

Addresses this request suppressed.

min 0

invalidInvalidAddress[]required

The entries that are not addresses, in the order given; nothing was done for them.

max items 1000

Show properties

Array of InvalidAddress

detailstringrequired

Why it is not an address.

indexintegerrequired

Its position in emails, from 0 (its pointer is /emails/{index}).

min 0

valuestringrequired

The entry as given.

201

For email: the suppression.

created_atTimestamprequired

emailstringrequired

The address as it was suppressed; it matches its key ignoring ASCII case.

evidenceobject | null

A summary of the evidence that created it; null for a manual suppression.

idId_Suppressionrequired

matches ^sup_[0-9a-f]{32}$

reasonSuppressionReasonrequired

Why an address is suppressed.

Allowed:unsubscribebouncecomplaintmanualaddress_changedaccount_closedno_mail_service

sourceSuppressionSourcerequired

Who or what created a suppression: a person, the recipient's unsubscribe, or the source of the delivery event that proved it.

Allowed:manualunsubscribesmtpprovider_apiprovider_webhookdsnarfinbound_notice

401

No valid credential.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

Allowed:invalid_requestunauthorizedforbiddensession_requirednot_foundarchivedmethod_not_allowedconflictinvalid_stateidempotency_in_progressprecondition_failedpayload_too_largeunsupported_media_typevalidation_failedidempotency_mismatchsuppressedcaptcha_failedinsufficient_scoperate_limitedquota_exceededinternal_errorservice_unavailabletimeout

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 people:write.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

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

For email: the address is suppressed already (conflict).

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

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: neither or both of email and emails, an email that is not an address, more than 1,000 emails, or a reason other than manual.

codeProblemCoderequired

The closed registry of problem codes: programs branch on a problem's code, never on its text. A code may be added, never repurposed.

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

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

Idempotency-Keyheader*A stable key for this logical request; reuse it when retrying.

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.norbelys.com/v1/suppressions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "no-mail@example.com",
    "Former.Customer@example.org",
    "not an address"
  ]
}'

const response = await fetch("https://api.norbelys.com/v1/suppressions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: "{\n  \"emails\": [\n    \"no-mail@example.com\",\n    \"Former.Customer@example.org\",\n    \"not an address\"\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.norbelys.com/v1/suppressions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Content-Type": "application/json"
    },
    data="{\n  \"emails\": [\n    \"no-mail@example.com\",\n    \"Former.Customer@example.org\",\n    \"not an address\"\n  ]\n}",
)

Response

{
  "already": 0,
  "created": 0,
  "invalid": [
    {
      "detail": "string",
      "index": 0,
      "value": "string"
    }
  ]
}

{
  "created_at": "2019-08-24T14:15:22Z",
  "email": "string",
  "evidence": {},
  "id": "sup_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "reason": "unsubscribe",
  "source": "manual"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}

{
  "code": "invalid_request",
  "detail": "string",
  "errors": [
    {
      "code": "string",
      "detail": "string",
      "pointer": "string"
    }
  ],
  "instance": "string",
  "request_id": "string",
  "retry_after": 0,
  "status": 0,
  "title": "string",
  "type": "string"
}