Update a sending domain: turn tracking on or off.

PATCH/v1/sending_domains/{id}

Authorization

AuthorizationBearer token · headerrequired

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

Path parameters

idId_SendingDomainrequired

The sending domain id (dom_…).

matches ^dom_[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

tracking_enabledbooleanrequired

Serve tracking links from it; verify then checks its CNAME.

Responses

200

The domain.

checked_atTimestamp | null

Show properties

One of:

Timestamp

string<date-time>

null

null

created_atTimestamprequired

hostnamestringrequired

The hostname, lowercase.

idId_SendingDomainrequired

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

last_errorobject | null

What the last check found wrong: {code, detail, at}.

recordsDnsRecord[]required

The records to publish: the ownership TXT record, the tracking CNAME when the hostname serves tracking links, and the managed MTA's DKIM key once it signs for the domain.

max items 3

Show properties

Array of DnsRecord

namestringrequired

The record's name.

purposestringrequired

ownership, tracking or dkim (the managed MTA's key).

statusstringrequired

What the last check observed: verified, missing or unchecked.

typestringrequired

TXT or CNAME.

valuestringrequired

The record's value.

statusstringrequired

pending_verification, verifying, verified, pending_certificate, active, suspended or deleting; new values may be added.

tracking_enabledbooleanrequired

Whether the hostname serves tracking links.

updated_atTimestamprequired

verified_atTimestamp | null

Show properties

One of:

Timestamp

string<date-time>

null

null

versioninteger<int64>required

The domain'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. Each DNS check moves it too.

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.

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 sending domain 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.

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

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

idpath*The sending domain id (`dom_…`).If-MatchheaderThe `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-KeyheaderA stable key for this logical request; reuse it when retrying.

Bodyapplication/json

tracking_enabledboolean*Serve tracking links from it; `verify` then checks its CNAME.

Request

curl -X PATCH 'https://api.norbelys.com/v1/sending_domains/dom_0190f8a2b4c87a10b6d2e4f6a8c0e2f4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "tracking_enabled": true
}'

const response = await fetch("https://api.norbelys.com/v1/sending_domains/dom_0190f8a2b4c87a10b6d2e4f6a8c0e2f4", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"tracking_enabled\": true\n}"
});

import requests

response = requests.patch(
    "https://api.norbelys.com/v1/sending_domains/dom_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"tracking_enabled\": true\n}",
)

Response

{
  "checked_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "hostname": "string",
  "id": "dom_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "last_error": {},
  "records": [
    {
      "name": "string",
      "purpose": "string",
      "status": "string",
      "type": "string",
      "value": "string"
    }
  ],
  "status": "string",
  "tracking_enabled": true,
  "updated_at": "2019-08-24T14:15:22Z",
  "verified_at": "2019-08-24T14:15:22Z",
  "version": 0
}

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

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

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

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

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

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