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
reasonHoldReasonrequired

Why an address is held (recipient_holds.reason).

Allowed:mailbox_fullgreylistedno_routeinvalid_recipient
review_afterTimestamprequired

When the hold is checked again.

null
null
reasonPreflightReasonrequired

Why an address got its verdict; parsed back from the cache (recipient_validations.reason).

Allowed:mximplicit_mxsyntaxno_domainnull_mxno_routedns_unavailable
statusPreflightStatusrequired

The verdict on an address: what POST /preflight reports and, for a verdict DNS answered, what the preflight cache keeps (recipient_validations.status); unknown is never cached.

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

Why an address is suppressed.

Allowed:unsubscribebouncecomplaintmanualaddress_changedaccount_closedno_mail_service
null
null
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:read.

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.

422

The body is invalid.

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.

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": "mailbox_full",
        "review_after": "2019-08-24T14:15:22Z"
      },
      "reason": "mx",
      "status": "routable",
      "suppression": {
        "id": "sup_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
        "reason": "unsubscribe"
      }
    }
  ]
}