---
seo:
  description: >-
    One /v1 of resources. Errors are RFC 9457 problems; lists are cursor pages;
    effectful requests take an Idempotency-Key.
sidebar:
  label: Overview
title: Norbelys API
---
One `/v1` of resources. Errors are RFC 9457 problems; lists are cursor pages; effectful requests take an `Idempotency-Key`.

Version v1

Base URL: `https://api.norbelys.com`

## Reports

- [`GET /v1/analytics`](/reference/reports/analytics-retrieve) — Retrieve the workspace's campaign counters.

## Campaigns

- [`GET /v1/campaigns`](/reference/campaigns/campaigns-list) — List the workspace's campaigns, newest first by default; the variants' bodies are left out.
- [`POST /v1/campaigns`](/reference/campaigns/campaigns-create) — Create a campaign as a \`draft\`, with its steps, pool, schedule, tracking and stop rules.
- [`GET /v1/campaigns/{id}`](/reference/campaigns/campaigns-retrieve) — Retrieve a campaign with its steps and their variants' bodies.
- [`DELETE /v1/campaigns/{id}`](/reference/campaigns/campaigns-delete) — Delete a campaign: one that never sent is removed with its steps and enrollments; one that sent is archived, kept for its history, and its live enrollments are stopped.
- [`PATCH /v1/campaigns/{id}`](/reference/campaigns/campaigns-update) — Change a campaign: its settings, its pool, or its steps (the whole ordered list; a changed step gets a new revision for messages not yet created).
- [`POST /v1/campaigns/{id}/pause`](/reference/campaigns/campaigns-pause) — Pause a campaign: no new message is created; queued messages wait until it is started again.
- [`POST /v1/campaigns/{id}/start`](/reference/campaigns/campaigns-start) — Start a campaign from \`draft\` or \`paused\`: it is \`materialising\` until its job makes it \`active\` and creates the messages already due.
- [`GET /v1/enrollments`](/reference/campaigns/enrollments-list) — List the workspace's enrollments, newest first by default.
- [`POST /v1/enrollments`](/reference/campaigns/enrollments-create) — Enroll people into a campaign: up to 100 at once (\`201\`), more through a job (\`202\`). Unknown people, suppressed addresses and people already enrolled are skipped.
- [`GET /v1/enrollments/{id}`](/reference/campaigns/enrollments-retrieve) — Retrieve an enrollment: its person, position, next run, status and the sender its conversation keeps or waits for.
- [`POST /v1/enrollments/{id}/stop`](/reference/campaigns/enrollments-stop) — Stop an enrollment: no further step runs, and its message still queued is cancelled.

## Sending

- [`GET /v1/connections`](/reference/sending/connections-list) — List the workspace's connections, newest first by default.
- [`POST /v1/connections`](/reference/sending/connections-create) — Create a connection. A credential-based one (SMTP, a relay, the managed MTA) is created in \`verifying\`, or the workspace's archived connection of the same account comes back with its id, history and identities; a check (or the managed MTA's provisioning) proves it. A Google or Microsoft mailbox answers \`202\` with the consent URL; the callback creates it.
- [`GET /v1/connections/{id}`](/reference/sending/connections-retrieve) — Retrieve a connection.
- [`DELETE /v1/connections/{id}`](/reference/sending/connections-delete) — Archive a connection: it stops sending, its credential is erased and its folders are no longer read, while its history stays readable and its provider webhook keeps receiving late evidence. Connecting the same account again restores it.
- [`PATCH /v1/connections/{id}`](/reference/sending/connections-update) — Update a connection: pause or resume it, change its pacing, identities or folders, or give it a new credential (then it is verified again).
- [`POST /v1/connections/{id}/verify`](/reference/sending/connections-verify) — Verify a connection now: it becomes \`verifying\` and its check runs (the managed MTA's provisioning, for a \`norbelys\` connection). For an OAuth connection whose grant is lost, the answer carries \`authorization.url\` for the browser instead, and the ceremony cookie.
- [`GET /v1/quota_scopes`](/reference/sending/quota-scopes-list) — List the workspace's quota scopes, newest first by default.
- [`POST /v1/quota_scopes`](/reference/sending/quota-scopes-create) — Create a quota scope.
- [`GET /v1/quota_scopes/{id}`](/reference/sending/quota-scopes-retrieve) — Retrieve a quota scope.
- [`DELETE /v1/quota_scopes/{id}`](/reference/sending/quota-scopes-delete) — Delete a quota scope and its ledger; its connections keep running without one. Refused while SES connections, archived ones included, name it.
- [`PATCH /v1/quota_scopes/{id}`](/reference/sending/quota-scopes-update) — Update a quota scope's limits: each limit given replaces the stored one, \`null\` clears it.
- [`GET /v1/sending_domains`](/reference/sending/sending-domains-list) — List the workspace's sending domains, newest first by default.
- [`POST /v1/sending_domains`](/reference/sending/sending-domains-create) — Create a sending domain, \`pending\_verification\`, with the DNS records to publish.
- [`GET /v1/sending_domains/{id}`](/reference/sending/sending-domains-retrieve) — Retrieve a sending domain.
- [`DELETE /v1/sending_domains/{id}`](/reference/sending/sending-domains-delete) — Delete a sending domain.
- [`PATCH /v1/sending_domains/{id}`](/reference/sending/sending-domains-update) — Update a sending domain: turn tracking on or off.
- [`POST /v1/sending_domains/{id}/verify`](/reference/sending/sending-domains-verify) — Verify a sending domain now: it becomes \`verifying\` and its DNS records are checked.

## Messages

- [`GET /v1/delivery_events`](/reference/messages/delivery-events-list) — List the workspace's delivery events, newest first by default.
- [`GET /v1/delivery_events/{id}`](/reference/messages/delivery-events-retrieve) — Retrieve a delivery event.
- [`GET /v1/messages`](/reference/messages/messages-list) — List the workspace's messages, newest first by default.
- [`POST /v1/messages`](/reference/messages/messages-create) — Send a message: it is queued now and sent when due, outside any campaign's cadence.
- [`GET /v1/messages/{id}`](/reference/messages/messages-retrieve) — Retrieve a message, with its latest attempts, its first delivery events and its holds.
- [`POST /v1/messages/{id}/cancel`](/reference/messages/messages-cancel) — Cancel a queued message.
- [`POST /v1/messages/{id}/release_holds`](/reference/messages/messages-release-holds) — Release a message's holds.
- [`POST /v1/messages/{id}/resolve`](/reference/messages/messages-resolve) — Resolve an uncertain message.

## Automation

- [`GET /v1/events`](/reference/automation/events-list) — List the workspace's events, newest first by default. With \`after\`, only later events, in ascending order unless \`order\` says otherwise; with \`wait\`, an empty page waits up to that many seconds (at most 25) for an event to arrive.
- [`POST /v1/events`](/reference/automation/events-create) — Create a synthetic event with sample data of its type. It is delivered like any other event, to every subscribed endpoint, or only to \`webhook\_endpoint\_id\` when given.
- [`GET /v1/events/{id}`](/reference/automation/events-retrieve) — Retrieve an event.
- [`GET /v1/jobs/{id}`](/reference/automation/jobs-retrieve) — Retrieve a job of the credential's workspace.
- [`POST /v1/jobs/{id}/cancel`](/reference/automation/jobs-cancel) — Request the cancellation of a job: a waiting job is cancelled at once, a running one at its next chunk boundary.
- [`GET /v1/webhook_deliveries`](/reference/automation/webhook-deliveries-list) — List the workspace's webhook deliveries, newest events first by default (the order is by event, then by delivery).
- [`GET /v1/webhook_deliveries/{id}`](/reference/automation/webhook-deliveries-retrieve) — Retrieve a webhook delivery with its latest attempt.
- [`POST /v1/webhook_deliveries/{id}/retry`](/reference/automation/webhook-deliveries-retry) — Retry a webhook delivery now. A pending delivery's next attempt is brought forward; a finished one becomes pending again. There is never a second run beside the automatic one.
- [`GET /v1/webhook_endpoints`](/reference/automation/webhook-endpoints-list) — List the workspace's webhook endpoints, newest first by default.
- [`POST /v1/webhook_endpoints`](/reference/automation/webhook-endpoints-create) — Create a webhook endpoint. Its signing secret (\`whsec\_…\`) is in this response only.
- [`GET /v1/webhook_endpoints/{id}`](/reference/automation/webhook-endpoints-retrieve) — Retrieve a webhook endpoint (without its secret).
- [`DELETE /v1/webhook_endpoints/{id}`](/reference/automation/webhook-endpoints-delete) — Delete a webhook endpoint and its deliveries.
- [`PATCH /v1/webhook_endpoints/{id}`](/reference/automation/webhook-endpoints-update) — Update a webhook endpoint: its URL, its event types, or whether it is enabled.
- [`POST /v1/webhook_endpoints/{id}/replay`](/reference/automation/webhook-endpoints-replay) — Replay an endpoint: every delivery of its events created at or after \`since\` becomes pending with its next attempt now. A disabled endpoint must be enabled first.
- [`POST /v1/webhook_endpoints/{id}/rotate_secret`](/reference/automation/webhook-endpoints-rotate-secret) — Rotate an endpoint's signing secret. The new secret is in this response only; the old one keeps signing for 24 hours, so every attempt carries both signatures meanwhile.

## Audience

- [`GET /v1/exports`](/reference/audience/exports-list) — List the workspace's exports, newest first by default.
- [`POST /v1/exports`](/reference/audience/exports-create) — Export a resource's list to a file. The export runs as a job: poll the export for its link, or listen for \`export.completed\`. History (\`messages\`, \`attempts\`, \`delivery\_events\`, \`inbound\_messages\`) includes the periods already archived out of the database.
- [`GET /v1/exports/{id}`](/reference/audience/exports-retrieve) — Retrieve an export, with a fresh download link when it is ready.
- [`GET /v1/fields`](/reference/audience/fields-list) — List the workspace's custom fields (at most 100).
- [`POST /v1/fields`](/reference/audience/fields-create) — Create a custom field.
- [`DELETE /v1/fields/{id}`](/reference/audience/fields-delete) — Delete a custom field and every person's value of it. A field a segment uses cannot be deleted.
- [`PATCH /v1/fields/{id}`](/reference/audience/fields-update) — Update a custom field's label or an enum's options. Its key and type never change.
- [`GET /v1/groups`](/reference/audience/groups-list) — List the workspace's groups, newest first by default, each with its people counted.
- [`POST /v1/groups`](/reference/audience/groups-create) — Create an empty group.
- [`GET /v1/groups/{id}`](/reference/audience/groups-retrieve) — Retrieve a group with its people counted.
- [`DELETE /v1/groups/{id}`](/reference/audience/groups-delete) — Delete a group and its memberships; its people stay.
- [`PATCH /v1/groups/{id}`](/reference/audience/groups-update) — Rename a group or change its description.
- [`GET /v1/imports`](/reference/audience/imports-list) — List the workspace's imports, newest first by default.
- [`POST /v1/imports`](/reference/audience/imports-create) — Import people from a CSV file (the body, \`Content-Type: text/csv\`, at most 16 MiB, its first record the header; \`group\_id\` as a query parameter) or from JSON (\`people\`, up to 1,000). The import runs as a job: poll the import, or listen for \`import.completed\`.
- [`GET /v1/imports/{id}`](/reference/audience/imports-retrieve) — Retrieve an import: its status, counts, first problems and the link to its error report.
- [`GET /v1/people`](/reference/audience/people-list) — List the workspace's people, newest first by default. With \`segment\_id\`, the people the segment's filter matches now.
- [`POST /v1/people`](/reference/audience/people-create) — Create a person.
- [`GET /v1/people/{id}`](/reference/audience/people-retrieve) — Retrieve a person.
- [`DELETE /v1/people/{id}`](/reference/audience/people-delete) — Delete a person and its memberships. A person with enrollments or messages cannot be deleted: its history refers to it.
- [`PATCH /v1/people/{id}`](/reference/audience/people-update) — Update a person: its address, names, company, custom values (merged) or groups (replaced).
- [`POST /v1/preflight`](/reference/audience/preflight-create) — 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.
- [`GET /v1/segments`](/reference/audience/segments-list) — List the workspace's segments, newest first by default. A list leaves the counts out.
- [`POST /v1/segments`](/reference/audience/segments-create) — Create a segment; the response counts its people.
- [`GET /v1/segments/{id}`](/reference/audience/segments-retrieve) — Retrieve a segment with its people counted now (up to 10,000).
- [`DELETE /v1/segments/{id}`](/reference/audience/segments-delete) — Delete a segment; its people stay.
- [`PATCH /v1/segments/{id}`](/reference/audience/segments-update) — Rename a segment or replace its filter.
- [`GET /v1/suppressions`](/reference/audience/suppressions-list) — List the workspace's suppressions, newest first by default.
- [`POST /v1/suppressions`](/reference/audience/suppressions-create) — Suppress an address: no mail of the workspace reaches it any more.
- [`GET /v1/suppressions/{id}`](/reference/audience/suppressions-retrieve) — Retrieve a suppression.
- [`DELETE /v1/suppressions/{id}`](/reference/audience/suppressions-delete) — Remove a manual suppression; the removal is audited. Suppressions that evidence created are read-only.

## Content

- [`POST /v1/images`](/reference/content/images-create) — Upload an image to show in mail. The file is the body, sent with its own \`Content-Type\` (\`image/png\`, \`image/jpeg\`, \`image/gif\` or \`image/webp\`), at most 16 MiB; its first bytes must be that format. The answer carries the image's public URL, to use in a message's or a variant's HTML.
- [`DELETE /v1/images/{id}`](/reference/content/images-delete) — Delete an image. Its public URL stops answering; mail already sent shows it no more, except where a cache kept a copy.

## Inbox

- [`GET /v1/inbound_messages`](/reference/inbox/inbound-messages-list) — List the messages the inbox read, newest first by default.
- [`GET /v1/inbound_messages/{id}`](/reference/inbox/inbound-messages-retrieve) — Retrieve a message the inbox read.
- [`PATCH /v1/inbound_messages/{id}`](/reference/inbox/inbound-messages-update) — Correct a message's classification or sentiment by hand; AI never overrides it afterwards.
- [`POST /v1/inbound_messages/{id}/review`](/reference/inbox/inbound-messages-review) — Confirm or dismiss what an inbound message proposed: confirming applies it (a suppression, or moving the person to the new address a notice gave).
- [`GET /v1/threads`](/reference/inbox/threads-list) — List the workspace's threads, newest first by default.
- [`GET /v1/threads/{id}`](/reference/inbox/threads-retrieve) — Retrieve a thread with its latest 50 messages, outbound and inbound, oldest first.
- [`PATCH /v1/threads/{id}`](/reference/inbox/threads-update) — Change a thread's status (open, snooze or archive it) or mark it read.

## Workspace

- [`GET /v1/workspaces/{id}`](/reference/workspace/workspaces-retrieve) — Retrieve a workspace.