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

Check addresses before mailing them: syntax, DNS routing (MX, an implicit MX, or a null MX that refuses all mail), and the workspace's suppressions and holds. Never a mailbox probe: nothing is sent to the addresses, and nothing is stored. A route the workspace's sending found in DNS within the last day is answered from that, as the sender reads it; any other is asked of DNS now, and a lookup DNS could not answer is `unknown`. In a test-mode workspace only the syntax is checked, as its sender does: its mail never leaves the fake transport.

POST/v1/preflight
Authorization
AuthorizationBearer token · headerrequired

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

Request body
requiredapplication/json
emailsstring[]required

1 to 100 addresses, each at most 320 characters.

Responses
200

One finding per address.

dataFinding[]required

One per address asked about, at most 100.

max items 100
Show properties
Array of Finding
detailstring | null

What is wrong with the address, when reason is syntax.

emailstringrequired

The address as given, trimmed.

holdHoldSummary | null
Show properties
One of:
HoldSummary
reasonstringrequired

mailbox_full, greylisted, no_route or invalid_recipient (a reported invalid address waiting for a person's review).

review_afterTimestamprequired

When the hold is checked again.

null
null
reasonstringrequired

Why: mx, implicit_mx (no MX record, the domain is its own mail host), syntax, no_domain, null_mx (the domain accepts no mail), no_route or dns_unavailable. New values may be added.

statusstringrequired

routable (mail has a route), invalid (no mail can reach it) or unknown (DNS did not answer; check again later). New values may be added.

suppressionSuppressionSummary | null
Show properties
One of:
SuppressionSummary
idId_Suppressionrequired
matches ^sup_[0-9a-f]{32}$
reasonstringrequired

Why the address is suppressed (unsubscribe, bounce, complaint, manual, …).

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

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
Bodyapplication/json
Request
curl -X POST 'https://api.norbelys.com/v1/preflight' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "ada@example.com",
    "not-an-address"
  ]
}'
Response
{
  "data": [
    {
      "detail": "string",
      "email": "string",
      "hold": {
        "reason": "string",
        "review_after": "2019-08-24T14:15:22Z"
      },
      "reason": "string",
      "status": "string",
      "suppression": {
        "id": "sup_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
        "reason": "string"
      }
    }
  ]
}