Norbelys API

One /v1 of resources. Errors are RFC 9457 problems; lists are cursor pages; effectful requests take an Idempotency-Key.

Reports

• GET
  Retrieve the workspace's campaign counters./v1/analytics

Campaigns

• GET
  List the workspace's campaigns, newest first by default; the variants' bodies are left out./v1/campaigns
• POST
  Create a campaign as a `draft`, with its steps, pool, schedule, tracking and stop rules./v1/campaigns
• GET
  Retrieve a campaign with its steps and their variants' bodies./v1/campaigns/{id}
• 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./v1/campaigns/{id}
• PATCH
  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)./v1/campaigns/{id}
• POST
  Pause a campaign: no new message is created; queued messages wait until it is started again./v1/campaigns/{id}/pause
• POST
  Start a campaign from `draft` or `paused`: it is `materialising` until its job makes it `active` and creates the messages already due./v1/campaigns/{id}/start
• GET
  List the workspace's enrollments, newest first by default./v1/enrollments
• POST
  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./v1/enrollments
• GET
  Retrieve an enrollment: its person, position, next run, status and the sender its conversation keeps or waits for./v1/enrollments/{id}
• POST
  Stop an enrollment: no further step runs, and its message still queued is cancelled./v1/enrollments/{id}/stop

Sending

• GET
  List the workspace's connections, newest first by default./v1/connections
• POST
  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./v1/connections
• GET
  Retrieve a connection./v1/connections/{id}
• 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./v1/connections/{id}
• PATCH
  Update a connection: pause or resume it, change its pacing, identities or folders, or give it a new credential (then it is verified again)./v1/connections/{id}
• POST
  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./v1/connections/{id}/verify
• GET
  List the workspace's quota scopes, newest first by default./v1/quota_scopes
• POST
  Create a quota scope./v1/quota_scopes
• GET
  Retrieve a quota scope./v1/quota_scopes/{id}
• DELETE
  Delete a quota scope and its ledger; its connections keep running without one. Refused while SES connections, archived ones included, name it./v1/quota_scopes/{id}
• PATCH
  Update a quota scope's limits: each limit given replaces the stored one, `null` clears it./v1/quota_scopes/{id}
• GET
  List the workspace's sending domains, newest first by default./v1/sending_domains
• POST
  Create a sending domain, `pending_verification`, with the DNS records to publish./v1/sending_domains
• GET
  Retrieve a sending domain./v1/sending_domains/{id}
• DELETE
  Delete a sending domain./v1/sending_domains/{id}
• PATCH
  Update a sending domain: turn tracking on or off./v1/sending_domains/{id}
• POST
  Verify a sending domain now: it becomes `verifying` and its DNS records are checked./v1/sending_domains/{id}/verify

Messages

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

Automation

• GET
  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./v1/events
• POST
  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./v1/events
• GET
  Retrieve an event./v1/events/{id}
• GET
  Retrieve a job of the credential's workspace./v1/jobs/{id}
• POST
  Request the cancellation of a job: a waiting job is cancelled at once, a running one at its next chunk boundary./v1/jobs/{id}/cancel
• GET
  List the workspace's webhook deliveries, newest events first by default (the order is by event, then by delivery)./v1/webhook_deliveries
• GET
  Retrieve a webhook delivery with its latest attempt./v1/webhook_deliveries/{id}
• POST
  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./v1/webhook_deliveries/{id}/retry
• GET
  List the workspace's webhook endpoints, newest first by default./v1/webhook_endpoints
• POST
  Create a webhook endpoint. Its signing secret (`whsec_…`) is in this response only./v1/webhook_endpoints
• GET
  Retrieve a webhook endpoint (without its secret)./v1/webhook_endpoints/{id}
• DELETE
  Delete a webhook endpoint and its deliveries./v1/webhook_endpoints/{id}
• PATCH
  Update a webhook endpoint: its URL, its event types, or whether it is enabled./v1/webhook_endpoints/{id}
• POST
  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./v1/webhook_endpoints/{id}/replay
• POST
  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./v1/webhook_endpoints/{id}/rotate_secret

Audience

• GET
  List the workspace's exports, newest first by default./v1/exports
• POST
  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./v1/exports
• GET
  Retrieve an export, with a fresh download link when it is ready./v1/exports/{id}
• GET
  List the workspace's custom fields (at most 100)./v1/fields
• POST
  Create a custom field./v1/fields
• DELETE
  Delete a custom field and every person's value of it. A field a segment uses cannot be deleted./v1/fields/{id}
• PATCH
  Update a custom field's label or an enum's options. Its key and type never change./v1/fields/{id}
• GET
  List the workspace's groups, newest first by default, each with its people counted./v1/groups
• POST
  Create an empty group./v1/groups
• GET
  Retrieve a group with its people counted./v1/groups/{id}
• DELETE
  Delete a group and its memberships; its people stay./v1/groups/{id}
• PATCH
  Rename a group or change its description./v1/groups/{id}
• GET
  List the workspace's imports, newest first by default./v1/imports
• POST
  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`./v1/imports
• GET
  Retrieve an import: its status, counts, first problems and the link to its error report./v1/imports/{id}
• GET
  List the workspace's people, newest first by default. With `segment_id`, the people the segment's filter matches now./v1/people
• POST
  Create a person./v1/people
• GET
  Retrieve a person./v1/people/{id}
• DELETE
  Delete a person and its memberships. A person with enrollments or messages cannot be deleted: its history refers to it./v1/people/{id}
• PATCH
  Update a person: its address, names, company, custom values (merged) or groups (replaced)./v1/people/{id}
• POST
  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./v1/preflight
• GET
  List the workspace's segments, newest first by default. A list leaves the counts out./v1/segments
• POST
  Create a segment; the response counts its people./v1/segments
• GET
  Retrieve a segment with its people counted now (up to 10,000)./v1/segments/{id}
• DELETE
  Delete a segment; its people stay./v1/segments/{id}
• PATCH
  Rename a segment or replace its filter./v1/segments/{id}
• GET
  List the workspace's suppressions, newest first by default./v1/suppressions
• POST
  Suppress an address: no mail of the workspace reaches it any more./v1/suppressions
• GET
  Retrieve a suppression./v1/suppressions/{id}
• DELETE
  Remove a manual suppression; the removal is audited. Suppressions that evidence created are read-only./v1/suppressions/{id}

Content

• POST
  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./v1/images
• DELETE
  Delete an image. Its public URL stops answering; mail already sent shows it no more, except where a cache kept a copy./v1/images/{id}

Inbox

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

Workspace

• GET
  Retrieve a workspace./v1/workspaces/{id}