{ "components": { "schemas": { "Account": { "description": "The account behind a connection.", "properties": { "email": { "description": "The mailbox's address, an SMTP login as it is, the From address a paced SES connection\npaces, or a name the customer gave a relay account.", "type": "string" }, "issuer": { "description": "For OAuth: the ID token's issuer.", "type": [ "string", "null" ] }, "subject": { "description": "For OAuth: the provider's immutable subject, kept through address changes and archive.", "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "Address": { "description": "An address and its display name.", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email" ], "type": "object" }, "AiSpend": { "description": "The month's AI spend, in micro-dollars (millionths of a US dollar).", "properties": { "budget_micros": { "description": "The month's budget: no call starts that could take spend and reservations past it.", "format": "int64", "type": "integer" }, "reserved_micros": { "description": "The bounds of the calls still running.", "format": "int64", "type": "integer" }, "spent_micros": { "description": "What settled calls cost.", "format": "int64", "type": "integer" } }, "required": [ "spent_micros", "reserved_micros", "budget_micros" ], "type": "object" }, "Allocation": { "description": "How a step revision assigns its variants (`step_revisions.allocation`).", "enum": [ "balanced", "weighted", "automatic" ], "type": "string", "x-open-enum": true }, "AnalyticsGroup": { "description": "One group of counters.", "properties": { "campaign_id": { "description": "The campaign, when grouped by campaign, step or variant.", "type": [ "string", "null" ] }, "counters": { "$ref": "#/components/schemas/Counters" }, "day": { "oneOf": [ { "$ref": "#/components/schemas/Date", "description": "The day, when grouped by day." }, { "type": "null" } ] }, "step_id": { "description": "The step, when grouped by step or variant.", "type": [ "string", "null" ] }, "variant_id": { "description": "The variant, when grouped by variant.", "type": [ "string", "null" ] }, "variant_version": { "description": "The variant's version, when grouped by variant: each published version counts apart.", "format": "int32", "type": [ "integer", "null" ] } }, "required": [ "counters" ], "type": "object" }, "AnalyticsObject": { "description": "The campaign counters of a range of days.", "properties": { "computed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "How far the rollup had counted when these were read; `null` before its first run." }, { "type": "null" } ] }, "data": { "description": "One entry per group, ordered by the grouping; empty when not grouped.", "items": { "$ref": "#/components/schemas/AnalyticsGroup" }, "maxItems": 2500, "type": "array" }, "from": { "$ref": "#/components/schemas/Date", "description": "The first day counted (UTC)." }, "group_by": { "oneOf": [ { "$ref": "#/components/schemas/GroupBy", "description": "How `data` is grouped; `null` when it is not." }, { "type": "null" } ] }, "has_more": { "description": "The grouping has more groups than `data` holds (at most 2,500).", "type": "boolean" }, "to": { "$ref": "#/components/schemas/Date", "description": "The last day counted (UTC), included." }, "totals": { "$ref": "#/components/schemas/Counters", "description": "The counters of the whole range and filters." } }, "required": [ "from", "to", "totals", "data", "has_more" ], "type": "object" }, "ApiCredentialInput": { "additionalProperties": false, "description": "A relay's API credential, used besides its SMTP credential for the daily account checks\n(Amazon SES: the account's sending state and its identities' verification) and to reconcile\nits events (SendGrid's Email Activity, Mailgun's events). It is stored sealed and never shown.", "properties": { "id": { "description": "Amazon SES: the AWS access key id (`AKIA…`); absent for SendGrid and Mailgun.", "type": [ "string", "null" ] }, "secret": { "description": "The AWS secret access key, or the SendGrid or Mailgun API key.", "type": "string" } }, "required": [ "secret" ], "type": "object" }, "AttachmentObject": { "description": "One immutable file with a short-lived download link.", "properties": { "content_id": { "description": "Inline Content-ID, when supplied by received MIME.", "type": [ "string", "null" ] }, "content_type": { "description": "MIME media type.", "type": "string" }, "created_at": { "$ref": "#/components/schemas/Timestamp", "description": "When this file entered storage." }, "download_url": { "description": "Bearer download link, valid for five minutes.", "type": "string" }, "filename": { "description": "Suggested download name; never a path in storage.", "type": "string" }, "id": { "$ref": "#/components/schemas/Id_Attachment", "description": "Typed file id." }, "size_bytes": { "description": "Decoded length in bytes.", "format": "int32", "type": "integer" } }, "required": [ "id", "filename", "content_type", "size_bytes", "created_at", "download_url" ], "type": "object" }, "AttemptObject": { "description": "One submission effort of a message.", "properties": { "category": { "oneOf": [ { "$ref": "#/components/schemas/EvidenceCategory", "description": "Why it ended as it did; null while it runs. New values may be added." }, { "type": "null" } ] }, "claimed_at": { "$ref": "#/components/schemas/Timestamp" }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "diagnostic": { "description": "The provider's words, bounded and redacted.", "type": [ "string", "null" ] }, "enhanced_status": { "type": [ "string", "null" ] }, "finished_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_Attempt" }, "number": { "description": "1 for the message's first attempt.", "format": "int32", "type": "integer" }, "outcome": { "oneOf": [ { "$ref": "#/components/schemas/AttemptOutcome", "description": "What the attempt came to; null while it runs. New values may be added." }, { "type": "null" } ] }, "phase": { "oneOf": [ { "$ref": "#/components/schemas/SubmissionPhase", "description": "The protocol step it ended in. New values may be added." }, { "type": "null" } ] }, "provider_message_id": { "description": "The provider's id of the accepted message, when it returns one.", "type": [ "string", "null" ] }, "recipient_count": { "format": "int32", "type": "integer" }, "smtp_code": { "format": "int32", "type": [ "integer", "null" ] }, "started_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the submission itself started." }, { "type": "null" } ] } }, "required": [ "id", "number", "connection_id", "recipient_count", "claimed_at" ], "type": "object" }, "AttemptOutcome": { "description": "What one attempt came to (`attempts.outcome`).", "enum": [ "accepted", "transient", "permanent", "uncertain", "released", "suppressed", "skipped" ], "type": "string", "x-open-enum": true }, "Authorization": { "description": "A consent the browser must give: open `url`, from the browser that received the ceremony\ncookie with this answer.", "properties": { "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the ceremony expires." }, "url": { "description": "The provider's consent page.", "type": "string" } }, "required": [ "url", "expires_at" ], "type": "object" }, "CampaignLastError": { "description": "What stops a campaign from sending.", "properties": { "at": { "$ref": "#/components/schemas/Timestamp" }, "code": { "description": "`no_sender` or `invalid`. New codes may be added.", "type": "string" }, "detail": { "type": "string" } }, "required": [ "code", "detail", "at" ], "type": "object" }, "CampaignObject": { "description": "A campaign as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "enrollments": { "oneOf": [ { "$ref": "#/components/schemas/EnrollmentSummary", "description": "Where the campaign's people are now and when its next email may go, counted whenever one\ncampaign is answered (retrieved, created, updated, started, paused, or archived by a\ndeletion); `null` in a list. Like `stats`, it is not part of `version`." }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_Campaign" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/CampaignLastError", "description": "Why the campaign cannot send right now, while that lasts: `no_sender` (no sender of the\npool is usable; its conversations wait and continue by themselves), `invalid` (it could\nnot start)." }, { "type": "null" } ] }, "name": { "type": "string" }, "schedule": { "$ref": "#/components/schemas/ScheduleObject" }, "senders": { "$ref": "#/components/schemas/SendersObject" }, "stats": { "$ref": "#/components/schemas/StatsObject" }, "status": { "$ref": "#/components/schemas/CampaignStatus" }, "steps": { "description": "The steps in order, with their variants (a list leaves out the variants' bodies).", "items": { "$ref": "#/components/schemas/StepObject" }, "maxItems": 50, "type": "array" }, "stop_rules": { "$ref": "#/components/schemas/StopRulesObject" }, "tracking": { "$ref": "#/components/schemas/TrackingObject" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The version an update's `If-Match` names.", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "status", "steps", "senders", "schedule", "tracking", "stop_rules", "stats", "version", "created_at", "updated_at" ], "type": "object" }, "CampaignStatus": { "description": "A campaign's lifecycle (`campaigns.status`).", "enum": [ "draft", "materialising", "active", "paused", "completed", "archived" ], "type": "string", "x-open-enum": true }, "ClassificationSource": { "description": "Who decided a classification (`inbound_messages.classification_source`).", "enum": [ "rules", "manual", "ai" ], "type": "string", "x-open-enum": true }, "Combine": { "description": "How a filter's conditions combine.", "enum": [ "all", "any" ], "type": "string", "x-open-enum": true }, "Condition": { "additionalProperties": false, "description": "One condition of a filter.", "properties": { "field": { "description": "`email`, `email_domain`, `given_name`, `family_name`, `company`, `created_at`, or a\ncustom field as `fields.`.", "type": "string" }, "operator": { "$ref": "#/components/schemas/Operator" }, "value": { "description": "What the field is compared with: absent for `exists` and `not_exists`, a list of 1 to\n100 values for `in`, one value of the field's type otherwise (an RFC 3339 instant for\n`created_at`)." } }, "required": [ "field", "operator" ], "type": "object" }, "ConnectionObject": { "description": "A connection as the API shows it.", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "authorization": { "oneOf": [ { "$ref": "#/components/schemas/Authorization", "description": "Present when the browser must give consent first." }, { "type": "null" } ] }, "checked_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The last check of the credential." }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "created_by": { "type": [ "string", "null" ] }, "daily_limit": { "description": "Submissions a UTC day.", "format": "int32", "type": "integer" }, "id": { "$ref": "#/components/schemas/Id_Connection" }, "identities": { "description": "The service's sender addresses.", "items": { "$ref": "#/components/schemas/IdentityObject" }, "maxItems": 1000, "type": "array" }, "imap": { "oneOf": [ { "$ref": "#/components/schemas/ImapSettings", "description": "The IMAP endpoint of an SMTP login." }, { "type": "null" } ] }, "paused": { "description": "The person's pause: sending stops, conversations wait.", "type": "boolean" }, "paused_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The breaker holds the connection until then." }, { "type": "null" } ] }, "provider": { "$ref": "#/components/schemas/Provider", "description": "The provider of the account; new values may be added." }, "quota_scope_id": { "type": [ "string", "null" ] }, "receiving": { "$ref": "#/components/schemas/ReceivingObject", "description": "The folders read, at most 10." }, "send_interval_minutes": { "description": "Minutes between campaign emails: exact whole minutes for Norbelys, 5-minute slots for mailboxes and SES; null when rate-paced.", "format": "int32", "type": [ "integer", "null" ] }, "send_window": { "oneOf": [ { "$ref": "#/components/schemas/SendWindow", "description": "When campaign mail may be submitted, in `timezone`." }, { "type": "null" } ] }, "smtp": { "oneOf": [ { "$ref": "#/components/schemas/SmtpSettings", "description": "The SMTP endpoint (relays, SMTP logins, the managed MTA)." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ConnectionStatus", "description": "Its health: `active` sends (unless `paused`), `authorization_required` waits for a new\ncredential or consent, `archived` ended. New values may be added." }, "status_detail": { "description": "The health text: what went wrong and what to do.", "type": [ "string", "null" ] }, "timezone": { "description": "The IANA time zone of the send window.", "type": "string" }, "transport": { "$ref": "#/components/schemas/Transport", "description": "What it submits over: SMTP, or the Gmail API or Microsoft Graph (`api`)." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "usage": { "$ref": "#/components/schemas/Usage" }, "version": { "description": "The connection's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplacement of `identities` or of the folders read never undoes a change made since it\nwas read. Health checks and the sender's pacing move it too.", "format": "int64", "type": "integer" }, "warmup_stage": { "description": "The warm-up stage; null when not warming.", "format": "int32", "type": [ "integer", "null" ] }, "webhook": { "oneOf": [ { "$ref": "#/components/schemas/WebhookObject", "description": "A relay's or the managed MTA's provider webhook." }, { "type": "null" } ] } }, "required": [ "id", "provider", "transport", "account", "status", "paused", "identities", "receiving", "daily_limit", "timezone", "usage", "created_at", "updated_at", "version" ], "type": "object" }, "ConnectionStatus": { "description": "A connection's lifecycle (`connections.status`).", "enum": [ "unverified", "verifying", "active", "authorization_required", "failed", "disabled", "archived" ], "type": "string", "x-open-enum": true }, "ConsentAnswer": { "description": "The `202` of a consent: open `authorization.url` in the browser that holds the ceremony\ncookie of this answer.", "properties": { "authorization": { "$ref": "#/components/schemas/Authorization" } }, "required": [ "authorization" ], "type": "object" }, "Counters": { "description": "The counters of a campaign, a step, a variant or a day, summed from `campaign_daily_stats`.", "properties": { "bounced": { "description": "Messages that could not reach their recipient for good.", "format": "int64", "type": "integer" }, "clicked": { "description": "Messages with at least one human click.", "format": "int64", "type": "integer" }, "complained": { "description": "Recipients who complained.", "format": "int64", "type": "integer" }, "delivered": { "description": "Messages the recipient's server took.", "format": "int64", "type": "integer" }, "opened": { "description": "Messages with at least one human open.", "format": "int64", "type": "integer" }, "replied": { "description": "Messages a person replied to.", "format": "int64", "type": "integer" }, "sent": { "description": "Messages a provider accepted.", "format": "int64", "type": "integer" }, "unsubscribed": { "description": "Recipients who unsubscribed.", "format": "int64", "type": "integer" } }, "required": [ "sent", "delivered", "bounced", "opened", "clicked", "replied", "unsubscribed", "complained" ], "type": "object" }, "CreateCampaign": { "additionalProperties": false, "description": "The body of `POST /campaigns`.", "properties": { "name": { "description": "1 to 200 characters.", "type": "string" }, "schedule": { "oneOf": [ { "$ref": "#/components/schemas/ScheduleInput" }, { "type": "null" } ] }, "senders": { "oneOf": [ { "$ref": "#/components/schemas/SendersInput" }, { "type": "null" } ] }, "steps": { "description": "The steps in order, at most 50, holding at most 1.5 MiB of names, prompts and templates.", "items": { "$ref": "#/components/schemas/StepInput" }, "type": [ "array", "null" ] }, "stop_rules": { "oneOf": [ { "$ref": "#/components/schemas/StopRulesInput" }, { "type": "null" } ] }, "tracking": { "oneOf": [ { "$ref": "#/components/schemas/TrackingInput" }, { "type": "null" } ] } }, "required": [ "name" ], "type": "object" }, "CreateConnection": { "additionalProperties": false, "description": "The body of `POST /connections`.", "properties": { "account_email": { "description": "The account (not for Google and Microsoft, whose address the provider names): an SMTP\nlogin, the From address of a paced SES connection, a managed domain or mailbox, or a\nrelay account name.", "type": [ "string", "null" ] }, "daily_limit": { "description": "Submissions a UTC day.", "format": "int32", "type": [ "integer", "null" ] }, "identities": { "description": "The From addresses, at most 1,000; a domain service starts without senders.", "items": { "$ref": "#/components/schemas/IdentityInput" }, "maxItems": 1000, "type": [ "array", "null" ] }, "imap": { "oneOf": [ { "$ref": "#/components/schemas/ImapInput", "description": "The IMAP endpoint of an SMTP login that is read." }, { "type": "null" } ] }, "provider": { "$ref": "#/components/schemas/Provider", "description": "`smtp`, `google`, `microsoft`, `ses`, `sendgrid`, `mailgun` or `norbelys`." }, "quota_scope_id": { "description": "The quota scope of the account; required for SES.", "type": [ "string", "null" ] }, "receiving": { "oneOf": [ { "$ref": "#/components/schemas/ReceivingInput", "description": "The folders to read (mailboxes); `INBOX` by default." }, { "type": "null" } ] }, "return_to": { "description": "Google and Microsoft: the dashboard path the browser returns to after the consent.", "type": [ "string", "null" ] }, "send_interval_minutes": { "description": "Minutes between campaign emails. Norbelys accepts exact whole minutes, 1 to 1,440.\nMailboxes and paced SES use 5-minute slots; mailboxes default to 10 minutes.\nSendGrid and Mailgun refuse an interval.", "format": "int32", "type": [ "integer", "null" ] }, "send_window": { "oneOf": [ { "$ref": "#/components/schemas/SendWindow", "description": "When campaign mail may be submitted." }, { "type": "null" } ] }, "smtp": { "oneOf": [ { "$ref": "#/components/schemas/SmtpInput", "description": "The SMTP endpoint and credential (SMTP logins and relays)." }, { "type": "null" } ] }, "timezone": { "description": "The send window's IANA time zone (`UTC` by default).", "type": [ "string", "null" ] }, "warmup_stage": { "description": "The warm-up stage to start at; absent when not warming.", "format": "int32", "type": [ "integer", "null" ] }, "webhook": { "oneOf": [ { "$ref": "#/components/schemas/WebhookInput", "description": "A relay's webhook verification material; may be given later." }, { "type": "null" } ] } }, "required": [ "provider" ], "type": "object" }, "CreateDomain": { "additionalProperties": false, "description": "The body of `POST /sending_domains`.", "properties": { "hostname": { "description": "The hostname, such as `links.example.com`.", "type": "string" }, "purpose": { "oneOf": [ { "$ref": "#/components/schemas/DomainPurpose", "description": "Use this hostname for tracking, sending, receiving, or both mail directions." }, { "type": "null" } ] }, "tracking_enabled": { "description": "Serve tracking links from it (its CNAME then points at Norbelys).", "type": [ "boolean", "null" ] }, "tracking_hostname": { "description": "Optional separate hostname for custom tracking on a mail domain.", "type": [ "string", "null" ] } }, "required": [ "hostname" ], "type": "object" }, "CreateEndpoint": { "additionalProperties": false, "description": "The body of `POST /webhook_endpoints`.", "properties": { "enabled": { "description": "Whether it receives events now (default true).", "type": [ "boolean", "null" ] }, "event_types": { "description": "The event types the endpoint receives, 1 to 32.", "items": { "$ref": "#/components/schemas/EventType" }, "type": "array" }, "filters": { "oneOf": [ { "$ref": "#/components/schemas/Filters", "description": "Resource filters; an empty object accepts every resource." }, { "type": "null" } ] }, "headers": { "additionalProperties": { "type": "string" }, "description": "Custom headers, replaced together, sealed at rest and never returned.", "propertyNames": { "type": "string" }, "type": [ "object", "null" ] }, "url": { "description": "Where events are POSTed: an `https` URL without credentials.", "type": "string" } }, "required": [ "url", "event_types" ], "type": "object" }, "CreateEnrollments": { "additionalProperties": false, "description": "The body of `POST /enrollments`: a campaign and exactly one source of people.", "properties": { "campaign_id": { "description": "The campaign (`cmp_…`).", "type": "string" }, "emails": { "description": "People by address, at most 1,000; an address that is no person of the workspace is\nskipped.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "group_id": { "description": "A group's members (`grp_…`).", "type": [ "string", "null" ] }, "person_ids": { "description": "People by id (`per_…`), at most 1,000.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "segment_id": { "description": "The people a segment matches (`seg_…`).", "type": [ "string", "null" ] } }, "required": [ "campaign_id" ], "type": "object" }, "CreateEvent": { "additionalProperties": false, "description": "The body of `POST /events`.", "properties": { "type": { "$ref": "#/components/schemas/EventType", "description": "The type of the synthetic event." }, "webhook_endpoint_id": { "description": "Address the event to this endpoint only, whatever its subscriptions.", "type": [ "string", "null" ] } }, "required": [ "type" ], "type": "object" }, "CreateExport": { "additionalProperties": false, "description": "The body of `POST /exports`.", "properties": { "filters": { "description": "The filters of the resource's list. For `people`: `email`, `group_id`, `segment_id`, `q`,\n`created_at[gte]` and the other ranges. For history, `created_at[gte]` and\n`created_at[lt]` (when a message was created, an attempt claimed, an event recorded, an\ninbound message received) and: for `messages`, `campaign_id`, `connection_id`,\n`person_id`, `thread_id`, `state`; for `attempts`, `message_id`, `connection_id`; for\n`delivery_events`, `message_id`, `kind`; for `inbound_messages`, `message_id`,\n`connection_id`, `person_id`, `thread_id`, `classification`.", "type": [ "object", "null" ] }, "format": { "oneOf": [ { "$ref": "#/components/schemas/ExportFormat", "description": "`csv` (the default) or `jsonl`." }, { "type": "null" } ] }, "resource": { "$ref": "#/components/schemas/ExportResource", "description": "What the file contains." } }, "required": [ "resource" ], "type": "object" }, "CreateField": { "additionalProperties": false, "description": "The body of `POST /fields`.", "properties": { "key": { "description": "How values are stored and named: a lowercase letter, then up to 63 lowercase letters,\ndigits or underscores; not a person attribute's name. It never changes.", "type": "string" }, "label": { "description": "The name people read, 1 to 100 characters.", "type": "string" }, "options": { "description": "An enum's allowed values: 1 to 100 distinct strings of 1 to 100 characters. Only for\n`enum`.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": { "$ref": "#/components/schemas/FieldType", "description": "The values' type; it never changes." } }, "required": [ "key", "label", "type" ], "type": "object" }, "CreateGroup": { "additionalProperties": false, "description": "The body of `POST /groups`.", "properties": { "description": { "description": "At most 1,000 characters.", "type": [ "string", "null" ] }, "name": { "description": "1 to 200 characters.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateImport": { "additionalProperties": false, "description": "The JSON body of `POST /imports`.", "properties": { "group_id": { "description": "The group every imported person joins.", "type": [ "string", "null" ] }, "people": { "description": "1 to 1,000 people, each `{email, given_name?, family_name?, company?, fields?}`; each is\nchecked by the import, which reports the invalid ones.", "items": { "type": "object" }, "type": "array" } }, "required": [ "people" ], "type": "object" }, "CreateMessage": { "additionalProperties": false, "description": "The direct form of `POST /messages`: a message with its own content from one\nof the workspace's sender identities.", "properties": { "attachments": { "description": "Uploaded attachments from this workspace, at most ten.", "items": { "$ref": "#/components/schemas/Id_Attachment" }, "type": "array" }, "bcc": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "cc": { "description": "At most 150 recipients in all, `to`, `cc` and `bcc` together, none twice.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When it stops being useful: not sent after this instant." }, { "type": "null" } ] }, "from": { "description": "The sender: a live, enabled identity or an address on a connected managed domain.\nNew addresses on a verified managed domain are registered automatically.", "type": "string" }, "html": { "description": "The one authored body, an HTML template; a plain-text alternative is derived from it.\nPrinted values are HTML-escaped. At most 256 KiB.", "type": "string" }, "send_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When to send it, at most 7 days ahead; now when absent or past." }, { "type": "null" } ] }, "subject": { "description": "A template: `{{ variables.name }}`, `{{ sender.name }}`, `{{ person.given_name }}` (when a\n`to` address is a person of the workspace). Printing a value that does not exist is an\nerror; `| default(\"…\")` or `{% if … %}` handle one that may be missing.", "type": "string" }, "to": { "description": "1 to 50 addresses.", "items": { "type": "string" }, "type": "array" }, "variables": { "description": "Values the templates read as `variables`; at most 64 KiB.", "type": [ "object", "null" ] } }, "required": [ "from", "to", "subject", "html" ], "type": "object" }, "CreatePerson": { "additionalProperties": false, "description": "The body of `POST /people`.", "properties": { "company": { "type": [ "string", "null" ] }, "email": { "description": "The address; unique in the workspace ignoring ASCII case.", "format": "email", "type": "string" }, "family_name": { "type": [ "string", "null" ] }, "fields": { "description": "Custom values by field key, each of its field's type.", "type": [ "object", "null" ] }, "given_name": { "description": "At most 200 characters; blank is absent.", "type": [ "string", "null" ] }, "group_ids": { "description": "The groups the person joins, at most 100.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "email" ], "type": "object" }, "CreatePreflight": { "additionalProperties": false, "description": "The body of `POST /preflight`.", "properties": { "emails": { "description": "1 to 100 addresses, each at most 320 characters.", "items": { "type": "string" }, "type": "array" } }, "required": [ "emails" ], "type": "object" }, "CreateQuotaScope": { "additionalProperties": false, "description": "The body of `POST /quota_scopes`.", "properties": { "messages_per_day": { "format": "int32", "type": [ "integer", "null" ] }, "provider": { "$ref": "#/components/schemas/Provider", "description": "The provider of the account." }, "recipients_per_day": { "format": "int32", "type": [ "integer", "null" ] }, "scope_key": { "description": "The account: a project id, a tenant id, `account:region`, a relay host.", "type": "string" }, "window_limit": { "description": "Units a short window allows; with `window_unit` and `window_seconds`, or none of them.", "format": "int32", "type": [ "integer", "null" ] }, "window_seconds": { "format": "int32", "type": [ "integer", "null" ] }, "window_unit": { "oneOf": [ { "$ref": "#/components/schemas/WindowUnit" }, { "type": "null" } ] } }, "required": [ "provider", "scope_key" ], "type": "object" }, "CreateReply": { "additionalProperties": false, "description": "The reply form of `POST /messages`: an answer in a thread, sent from the thread's own sender\nidentity, answering the thread's latest inbound message (or, without one, its latest\noutbound message).", "properties": { "attachments": { "description": "Uploaded attachments from this workspace, at most ten.", "items": { "$ref": "#/components/schemas/Id_Attachment" }, "type": "array" }, "bcc": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "cc": { "description": "At most 150 recipients in all, `to`, `cc` and `bcc` together, none twice.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When it stops being useful: not sent after this instant." }, { "type": "null" } ] }, "html": { "description": "The one authored body, an HTML template; a plain-text alternative is derived from it.\nAt most 256 KiB.", "type": "string" }, "send_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When to send it, at most 7 days ahead; now when absent or past." }, { "type": "null" } ] }, "subject": { "description": "A template; `Re: ` and the thread's subject, as it is, when absent.", "type": [ "string", "null" ] }, "thread_id": { "description": "The thread (`thr_…`).", "type": "string" }, "to": { "description": "1 to 50 addresses; the sender of the thread's latest inbound message when absent.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "variables": { "description": "Values the templates read as `variables`; at most 64 KiB.", "type": [ "object", "null" ] } }, "required": [ "thread_id", "html" ], "type": "object" }, "CreateSegment": { "additionalProperties": false, "description": "The body of `POST /segments`.", "properties": { "filter": { "$ref": "#/components/schemas/Filter", "description": "Who the segment means." }, "name": { "description": "1 to 200 characters.", "type": "string" } }, "required": [ "name", "filter" ], "type": "object" }, "CreateStepMessage": { "additionalProperties": false, "description": "The step-content form of `POST /messages` for one person who is not enrolled: the campaign\nstep's content in that person's version, or a preview of it at another address. Answers the\nmessage.", "properties": { "from": { "description": "The sender: a sender identity's id (`sid_…`) or its address; the campaign pool's next\nusable sender when absent.", "type": [ "string", "null" ] }, "person_id": { "description": "The person whose version is sent (`per_…`).", "type": "string" }, "send_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When to send it, at most 7 days ahead; now when absent or past." }, { "type": "null" } ] }, "step_id": { "description": "The step (`stp_…`): its winner's content, else its first variant's.", "type": [ "string", "null" ] }, "to": { "description": "That person's version goes to this address instead, which is how a step is previewed;\nthe variant's `cc` and `bcc` are left out.", "type": [ "string", "null" ] }, "variables": { "description": "Values the templates read as `variables`; at most 64 KiB.", "type": [ "object", "null" ] }, "variant_id": { "description": "The variant (`var_…`), at its latest version; with `step_id`, one of the step's.", "type": [ "string", "null" ] } }, "required": [ "person_id" ], "type": "object" }, "CreateStepMessages": { "additionalProperties": false, "description": "The step-content form of `POST /messages` for several people who are not enrolled: each is\nsent their version of the campaign step. Answers a result per person, the message or the\nproblem a single request would have answered.", "properties": { "from": { "description": "The sender: a sender identity's id (`sid_…`) or its address; the campaign pool's next\nusable sender when absent.", "type": [ "string", "null" ] }, "person_ids": { "description": "1 to 100 people (`per_…`), each sent their version.", "items": { "type": "string" }, "type": "array" }, "send_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When to send them, at most 7 days ahead; now when absent or past." }, { "type": "null" } ] }, "step_id": { "description": "The step (`stp_…`): its winner's content, else its first variant's.", "type": [ "string", "null" ] }, "variables": { "description": "Values the templates read as `variables`; at most 64 KiB.", "type": [ "object", "null" ] }, "variant_id": { "description": "The variant (`var_…`), at its latest version; with `step_id`, one of the step's.", "type": [ "string", "null" ] } }, "required": [ "person_ids" ], "type": "object" }, "CreateSuppression": { "additionalProperties": false, "description": "The one-address form of `POST /suppressions`: answers the suppression (`201`).", "properties": { "email": { "description": "The address to stop mailing.", "format": "email", "type": "string" }, "reason": { "oneOf": [ { "$ref": "#/components/schemas/SuppressionReason", "description": "Always `manual` (the default): every other reason comes from evidence." }, { "type": "null" } ] } }, "required": [ "email" ], "type": "object" }, "CreateSuppressions": { "additionalProperties": false, "description": "The list form of `POST /suppressions`: up to 1,000 addresses suppressed as one decision,\nanswered with what it did (`200`).", "properties": { "emails": { "description": "1 to 1,000 addresses to stop mailing. Each entry is read on its own: one that is not an\naddress is reported in `invalid` and the others are suppressed; an address given twice,\nin any case, counts once.", "items": { "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" }, "reason": { "oneOf": [ { "$ref": "#/components/schemas/SuppressionReason", "description": "Always `manual` (the default): every other reason comes from evidence." }, { "type": "null" } ] } }, "required": [ "emails" ], "type": "object" }, "Date": { "format": "date", "type": "string" }, "Decision": { "description": "What a person decides.", "enum": [ "confirm", "dismiss" ], "type": "string" }, "DeliveryEventKind": { "description": "What kind of observation a delivery event is (`delivery_events.kind`).", "enum": [ "accepted", "deferred", "delivered", "bounced", "rejected", "complaint", "unsubscribed", "address_changed", "reported" ], "type": "string", "x-open-enum": true }, "DeliveryEventObject": { "description": "One observation about a message's fate.", "properties": { "action": { "oneOf": [ { "$ref": "#/components/schemas/DsnAction", "description": "The RFC 3464 action, for a delivery status notification." }, { "type": "null" } ] }, "attempt_number": { "description": "The attempt it comes from, when its source is an attempt.", "format": "int32", "type": [ "integer", "null" ] }, "category": { "$ref": "#/components/schemas/EvidenceCategory", "description": "Why it happened, in the closed vocabulary of evidence. New values may be added." }, "confidence": { "$ref": "#/components/schemas/EvidenceConfidence", "description": "How far the observation can be trusted. New values may be added." }, "diagnostic": { "type": [ "string", "null" ] }, "enhanced_status": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/Id_DeliveryEvent" }, "kind": { "$ref": "#/components/schemas/DeliveryEventKind", "description": "What was observed. New values may be added." }, "message_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "The message, when the evidence could be matched to one." }, { "type": "null" } ] }, "observed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the source observed it." }, "phase": { "oneOf": [ { "$ref": "#/components/schemas/SubmissionPhase", "description": "The protocol step a submission's answer came from, for the `smtp` and `provider_api`\nsources." }, { "type": "null" } ] }, "processed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When Norbelys recorded it." }, "provider_code": { "description": "An exact provider-specific rejection code found in `diagnostic`, when any; it does not\nchange the event's kind, recipient effect, or retry decision.", "type": [ "string", "null" ] }, "received_at": { "$ref": "#/components/schemas/Timestamp", "description": "When Norbelys received it." }, "recipient": { "description": "The recipient it concerns; null when the evidence names none.", "type": [ "string", "null" ] }, "recipient_ref": { "$ref": "#/components/schemas/RecipientRef", "description": "Why the recipient is known. New values may be added." }, "source": { "$ref": "#/components/schemas/EvidenceSource", "description": "Where the observation came from. New values may be added." }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread" }, { "type": "null" } ] } }, "required": [ "id", "kind", "source", "confidence", "recipient_ref", "category", "observed_at", "received_at", "processed_at" ], "type": "object" }, "DeliveryObject": { "description": "A delivery as the API shows it.", "properties": { "attempts": { "description": "Attempts made so far.", "format": "int32", "type": "integer" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "delivered_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "event_id": { "$ref": "#/components/schemas/Id_OutboxEvent" }, "event_type": { "$ref": "#/components/schemas/EventType", "description": "The event's type." }, "id": { "$ref": "#/components/schemas/Id_WebhookDelivery" }, "last_attempt": { "oneOf": [ { "$ref": "#/components/schemas/LastAttempt", "description": "The latest attempt, failures included." }, { "type": "null" } ] }, "next_attempt_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the next attempt is due, while `pending`." }, { "type": "null" } ] }, "state": { "$ref": "#/components/schemas/WebhookDeliveryState", "description": "Where the delivery is. New values may be added." }, "webhook_endpoint_id": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } }, "required": [ "id", "event_id", "event_type", "webhook_endpoint_id", "state", "attempts", "created_at" ], "type": "object" }, "Direction": { "description": "Which side of a conversation supplied a message, shared by thread and history reads.", "enum": [ "outbound", "inbound" ], "type": "string", "x-open-enum": true }, "DnsPreparation": { "description": "Publication preparation is independent of DNS ownership verification.", "enum": [ "preparing", "ready", "unavailable" ], "type": "string", "x-open-enum": true }, "DnsRecord": { "description": "A DNS record a sending domain publishes.", "properties": { "name": { "description": "The record's name.", "type": "string" }, "note": { "description": "Publication advice from the managed MTA, including how to preserve existing DNS records.", "type": [ "string", "null" ] }, "priority": { "description": "The MX preference; absent for other record types.", "format": "int32", "minimum": 0, "type": [ "integer", "null" ] }, "purpose": { "$ref": "#/components/schemas/DnsRecordPurpose" }, "status": { "$ref": "#/components/schemas/DnsRecordStatus" }, "type": { "$ref": "#/components/schemas/DnsRecordType" }, "value": { "description": "The record's value.", "type": "string" } }, "required": [ "type", "name", "value", "purpose", "status" ], "type": "object" }, "DnsRecordPurpose": { "description": "What a DNS record proves or serves: ownership, tracking, or managed sending authentication.", "enum": [ "ownership", "tracking", "spf", "dmarc", "dkim", "mx" ], "type": "string", "x-open-enum": true }, "DnsRecordStatus": { "description": "What the last check of a DNS record observed: the record as expected, its absence, or no\ncheck yet.", "enum": [ "verified", "missing", "unchecked" ], "type": "string", "x-open-enum": true }, "DnsRecordType": { "description": "The type of a DNS record to publish.", "enum": [ "TXT", "CNAME", "MX" ], "type": "string", "x-open-enum": true }, "DomainObject": { "description": "A sending domain as the API shows it.", "properties": { "checked_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "dns_preparation": { "$ref": "#/components/schemas/DnsPreparation", "description": "Whether publication instructions are being prepared, ready, or unavailable on this installation." }, "existing_mx": { "description": "Existing MX targets discovered during DNS preparation or verification.", "items": { "$ref": "#/components/schemas/MailExchange" }, "maxItems": 64, "type": "array" }, "hostname": { "description": "The hostname, lowercase.", "type": "string" }, "id": { "$ref": "#/components/schemas/Id_SendingDomain" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "What the last check found wrong." }, { "type": "null" } ] }, "purpose": { "$ref": "#/components/schemas/DomainPurpose", "description": "The intended use of this hostname; mail and CNAME tracking use separate names." }, "records": { "description": "The records to publish: the ownership TXT record, the tracking CNAME when the hostname\nserves tracking links, and the managed MTA's SPF, DMARC and DKIM records once rendered.\nSPF and DMARC are publication instructions and remain `unchecked`.", "items": { "$ref": "#/components/schemas/DnsRecord" }, "maxItems": 5, "type": "array" }, "status": { "$ref": "#/components/schemas/SendingDomainStatus", "description": "Where the domain is in its lifecycle; new values may be added." }, "tracking_domain": { "oneOf": [ { "$ref": "#/components/schemas/TrackingDomainObject", "description": "Optional custom tracking hosted at another hostname." }, { "type": "null" } ] }, "tracking_enabled": { "description": "Whether the hostname serves tracking links.", "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "verified_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "version": { "description": "The domain's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version. Each DNS\ncheck moves it too.", "format": "int64", "type": "integer" }, "warnings": { "description": "Existing-provider and DNS conflict advice; no existing DNS record is changed by the API.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "hostname", "status", "tracking_enabled", "purpose", "dns_preparation", "existing_mx", "warnings", "records", "created_at", "updated_at", "version" ], "type": "object" }, "DomainPurpose": { "description": "What this hostname is used for. Mail and CNAME tracking use separate hostnames.", "enum": [ "tracking", "send", "receive", "send_receive" ], "type": "string", "x-open-enum": true }, "DsnAction": { "description": "What a delivery status notification says happened to a recipient (RFC 3464 §2.3.3,\n), when the evidence is one.", "enum": [ "failed", "delayed", "delivered", "relayed", "expanded" ], "type": "string", "x-open-enum": true }, "EndpointDisabledReason": { "description": "Why an endpoint was disabled (`webhook_endpoints.disabled_reason`).", "enum": [ "gone", "failing", "manual" ], "type": "string", "x-open-enum": true }, "EndpointObject": { "description": "An endpoint as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "disabled_reason": { "oneOf": [ { "$ref": "#/components/schemas/EndpointDisabledReason", "description": "Why it was disabled: it answered `410` (`gone`), it failed for 5 days without a success\n(`failing`), or a person disabled it (`manual`). Null while enabled. New values may be added." }, { "type": "null" } ] }, "enabled": { "description": "False once disabled, by a person or by its failures.", "type": "boolean" }, "event_types": { "description": "The event types the endpoint receives.", "items": { "$ref": "#/components/schemas/EventType" }, "type": "array" }, "failing_since": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The first failed attempt since the last success." }, { "type": "null" } ] }, "filters": { "$ref": "#/components/schemas/Filters", "description": "Resource filters applied together with the event types." }, "header_names": { "description": "Configured header names; their values are never returned.", "items": { "type": "string" }, "type": "array" }, "id": { "$ref": "#/components/schemas/Id_WebhookEndpoint" }, "secret": { "description": "The signing secret, shown only when the endpoint is created or its secret rotated.", "type": [ "string", "null" ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "url": { "type": "string" }, "version": { "description": "The endpoint's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplaced list of event types never undoes a change made since it was read. A failure or\na disabling by the worker moves it too.", "format": "int64", "type": "integer" } }, "required": [ "id", "url", "event_types", "filters", "header_names", "enabled", "created_at", "updated_at", "version" ], "type": "object" }, "Enrolled": { "description": "What an inline enrollment did.", "properties": { "data": { "description": "The enrollments created.", "items": { "$ref": "#/components/schemas/EnrollmentObject" }, "maxItems": 100, "type": "array" }, "skipped": { "description": "The people that were not enrolled, and why.", "items": { "$ref": "#/components/schemas/Skipped" }, "maxItems": 100, "type": "array" } }, "required": [ "data", "skipped" ], "type": "object" }, "EnrollmentObject": { "description": "An enrollment as the API shows it.", "properties": { "campaign_id": { "$ref": "#/components/schemas/Id_Campaign" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Enrollment" }, "message_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "The current step's message, while it is on its way." }, { "type": "null" } ] }, "next_run_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When its current step is due; `null` while the step's message is on its way, or once\nit ended." }, { "type": "null" } ] }, "person": { "$ref": "#/components/schemas/PersonRef" }, "position": { "description": "The step it is at, 1 for the first.", "format": "int32", "type": "integer" }, "sender_identity_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_SenderIdentity", "description": "The sender its conversation keeps, once one was assigned." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/EnrollmentStatus" }, "status_detail": { "description": "Why it ended, when it ended early.", "type": [ "string", "null" ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "waiting_for": { "oneOf": [ { "$ref": "#/components/schemas/Id_SenderIdentity", "description": "The sender the next step waits for, while that sender is unavailable." }, { "type": "null" } ] } }, "required": [ "id", "campaign_id", "person", "status", "position", "created_at", "updated_at" ], "type": "object" }, "EnrollmentStatus": { "description": "An enrollment's lifecycle (`enrollments.status`).", "enum": [ "active", "paused", "completed", "replied", "stopped", "failed" ], "type": "string", "x-open-enum": true }, "EnrollmentSummary": { "description": "A campaign's enrollments as they stand: how many are in each status, how many live ones are\nat each step, and when the campaign's next email may go.", "properties": { "active": { "description": "Live enrollments whose steps run.", "format": "int64", "type": "integer" }, "completed": { "description": "Enrollments that went through the campaign's last step.", "format": "int64", "type": "integer" }, "failed": { "description": "Enrollments that ended because a step could not be sent.", "format": "int64", "type": "integer" }, "next_run_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the campaign's next email may go: the earliest time an `active` enrollment's next\nstep is due, never before now, moved to the next opening of the campaign's send window;\nan enrollment whose email is already on its way counts as due now. `null` when the\ncampaign is not sending (`draft`, `paused`, `completed` or `archived`) or no active\nenrollment has a step to come. The sender's pacing, daily limit and own send window may\nsend it later." }, { "type": "null" } ] }, "paused": { "description": "Live enrollments held for now: their steps wait.", "format": "int64", "type": "integer" }, "replied": { "description": "Enrollments that ended because the person replied.", "format": "int64", "type": "integer" }, "steps": { "description": "Every step of the campaign, in order, with its live enrollments (`active` or `paused`):\nthose whose email from this step is due or on its way. A live enrollment whose step was\nremoved counts in its status but at no step, until the next pass completes it.", "items": { "$ref": "#/components/schemas/StepEnrollments" }, "maxItems": 50, "type": "array" }, "stopped": { "description": "Enrollments stopped by a person, a stop rule, a suppression or a sender that left the\npool.", "format": "int64", "type": "integer" } }, "required": [ "active", "paused", "completed", "replied", "stopped", "failed", "steps" ], "type": "object" }, "EventObject": { "description": "An event as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "data": { "description": "What consumers receive." }, "id": { "$ref": "#/components/schemas/Id_OutboxEvent" }, "synthetic": { "description": "True for an event created on request (`POST /events`) rather than by a real change.", "type": "boolean" }, "type": { "$ref": "#/components/schemas/EventType", "description": "The event's type, such as `message.sent`. New types may be added." }, "webhook_endpoint_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_WebhookEndpoint", "description": "The one endpoint a synthetic event is addressed to, if any." }, { "type": "null" } ] } }, "required": [ "id", "type", "data", "synthetic", "created_at" ], "type": "object" }, "EventType": { "description": "The type of an event: the closed vocabulary webhook endpoints subscribe to. New types may be added.", "enum": [ "message.queued", "message.sent", "message.failed", "message.uncertain", "message.cancelled", "message.snippets_fallback", "delivery_event.recorded", "inbound_message.received", "enrollment.stopped", "enrollment.completed", "campaign.status_changed", "connection.health_changed", "import.completed", "export.completed", "suppression.created", "ai.budget_warning", "ai.budget_exceeded", "endpoint.test", "webhook_endpoint.disabled" ], "type": "string", "x-open-enum": true }, "EvidenceCategory": { "description": "Why an outcome happened, in a closed vocabulary (`attempts.category`,\n`delivery_events.category`).", "enum": [ "accepted", "invalid_recipient", "mailbox_full", "no_route", "invalid_address", "content_rejected", "policy", "throttled", "unauthorized", "forbidden", "connection_failed", "deadline", "unsupported", "transient", "rejected", "uncertain", "delivered", "complaint", "unsubscribed", "address_changed", "expired", "suppressed", "sender_archived", "render_failed", "workspace_deleted" ], "type": "string", "x-open-enum": true }, "EvidenceConfidence": { "description": "How much a delivery event can be trusted (`delivery_events.confidence`).", "enum": [ "authenticated", "corroborated", "inferred", "human_text" ], "type": "string", "x-open-enum": true }, "EvidenceSource": { "description": "Where a delivery event came from (`delivery_events.source`).", "enum": [ "smtp", "provider_api", "provider_webhook", "dsn", "arf", "inbound_notice", "preflight", "unsubscribe", "manual", "sent_folder" ], "type": "string", "x-open-enum": true }, "ExportFormat": { "description": "The file's format.", "enum": [ "csv", "jsonl" ], "type": "string", "x-open-enum": true }, "ExportObject": { "description": "An export as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the file is deleted." }, "filters": { "description": "The filters of the resource's list the file applies.", "type": "object" }, "format": { "$ref": "#/components/schemas/ExportFormat", "description": "The file's format." }, "id": { "$ref": "#/components/schemas/Id_Export" }, "job_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Job", "description": "The job doing the work." }, { "type": "null" } ] }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "Why the export failed." }, { "type": "null" } ] }, "resource": { "$ref": "#/components/schemas/ExportResource", "description": "What the file contains. New values may be added." }, "rows": { "description": "The rows in the file, once it is ready.", "format": "int64", "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/ExportStatus", "description": "Where the export is. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "url": { "description": "The file, when `ready`: a link that works for 15 minutes from this read.", "type": [ "string", "null" ] } }, "required": [ "id", "resource", "filters", "format", "status", "expires_at", "created_at", "updated_at" ], "type": "object" }, "ExportResource": { "description": "What an export contains.", "enum": [ "people", "messages", "attempts", "delivery_events", "inbound_messages" ], "type": "string", "x-open-enum": true }, "ExportStatus": { "description": "Where an export is, as the API shows it: `queued` and `running` while its job writes the file,\n`ready` with a link, `failed`, or `expired` once its file's days are over. The row stores the\nfirst four; `expired` is read from `expires_at`, and a job that ended without finishing reads\nas `failed`.", "enum": [ "queued", "running", "ready", "failed", "expired" ], "type": "string", "x-open-enum": true }, "Family": { "description": "Which metric family to retrieve.", "enum": [ "events", "rates", "usage" ], "type": "string", "x-open-enum": true }, "FieldError": { "description": "One invalid field of a `validation_failed` problem.", "properties": { "code": { "description": "What is wrong (`required`, `range`, `length`, `format`, `invalid`, …).", "type": "string" }, "detail": { "description": "A safe, human-readable explanation.", "type": "string" }, "pointer": { "description": "RFC 6901 pointer into the body, or `?name` for a query parameter.", "type": "string" } }, "required": [ "pointer", "code", "detail" ], "type": "object" }, "FieldObject": { "description": "A custom field definition as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Field" }, "key": { "description": "How values are stored in a person's `fields` and named in imports and segments.", "type": "string" }, "label": { "description": "The name people read.", "type": "string" }, "options": { "description": "An enum field's allowed values; empty for every other type.", "items": { "type": "string" }, "type": "array" }, "type": { "$ref": "#/components/schemas/FieldType", "description": "What its values are. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The field's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplacement of `options` never undoes a change made since it was read.", "format": "int64", "type": "integer" } }, "required": [ "id", "key", "label", "type", "options", "created_at", "updated_at", "version" ], "type": "object" }, "FieldType": { "description": "The type of a custom field.", "enum": [ "text", "number", "boolean", "enum", "date" ], "type": "string", "x-open-enum": true }, "Filter": { "additionalProperties": false, "description": "A segment's filter, as written and stored.", "properties": { "conditions": { "description": "The conditions, 1 to 20.", "items": { "$ref": "#/components/schemas/Condition" }, "maxItems": 20, "minItems": 1, "type": "array" }, "match": { "$ref": "#/components/schemas/Combine", "description": "`all` (the default): a person matches when every condition holds; `any`: when at least\none does." } }, "required": [ "conditions" ], "type": "object" }, "Filters": { "additionalProperties": false, "description": "Resource restrictions on a webhook subscription.", "properties": { "campaign_ids": { "description": "Campaigns whose events are wanted; empty means any campaign.", "items": { "$ref": "#/components/schemas/Id_Campaign" }, "type": "array" }, "connection_ids": { "description": "Connections whose events are wanted; empty means any connection.", "items": { "$ref": "#/components/schemas/Id_Connection" }, "type": "array" } }, "type": "object" }, "Finding": { "description": "What preflight found for one address.", "properties": { "detail": { "description": "What is wrong with the address, when `reason` is `syntax`.", "type": [ "string", "null" ] }, "email": { "description": "The address as given, trimmed.", "type": "string" }, "hold": { "oneOf": [ { "$ref": "#/components/schemas/HoldSummary", "description": "The address's active hold: mail to it waits until the hold is lifted." }, { "type": "null" } ] }, "reason": { "$ref": "#/components/schemas/PreflightReason", "description": "Why: `mx`, `implicit_mx` (no MX record, the domain is its own mail host), `syntax`,\n`no_domain`, `null_mx` (the domain accepts no mail), `no_route` or `dns_unavailable`.\nNew values may be added." }, "smtp": { "oneOf": [ { "$ref": "#/components/schemas/MailboxFinding", "description": "Optional SMTP recipient check, separate from DNS routing. `accepted` is not proof of\ndelivery; `unknown` and `skipped` do not prevent normal sending." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/PreflightStatus", "description": "`routable` (mail has a route), `invalid` (no mail can reach it) or `unknown` (DNS did not\nanswer; check again later). New values may be added." }, "suppression": { "oneOf": [ { "$ref": "#/components/schemas/SuppressionSummary", "description": "The workspace's suppression of the address: no mail is ever sent to it." }, { "type": "null" } ] } }, "required": [ "email", "status", "reason" ], "type": "object" }, "FolderObject": { "description": "One folder a connection reads.", "properties": { "enabled": { "description": "Whether it is read.", "type": "boolean" }, "failures": { "description": "Consecutive failed reads.", "format": "int32", "type": "integer" }, "folder": { "description": "The folder's name at the provider (`INBOX`).", "type": "string" }, "id": { "$ref": "#/components/schemas/Id_ReceiveBinding" }, "polled_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When it was last read." }, { "type": "null" } ] }, "status_detail": { "description": "What the last failed read said.", "type": [ "string", "null" ] } }, "required": [ "id", "folder", "enabled", "failures" ], "type": "object" }, "GroupBy": { "description": "How `GET /analytics` groups its counters.", "enum": [ "day", "campaign", "step", "variant" ], "type": "string", "x-open-enum": true }, "GroupObject": { "description": "A group as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "description": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/Id_Group" }, "name": { "type": "string" }, "people_count": { "description": "The people in the group, counted now; not part of `version`, since no update writes it.", "format": "int64", "type": "integer" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The group's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version.", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "people_count", "created_at", "updated_at", "version" ], "type": "object" }, "HistoryMessage": { "description": "One result in ingestion order, with no large bodies or download links.", "properties": { "connection_id": { "$ref": "#/components/schemas/Id_Connection", "description": "The connection used to send or receive it." }, "created_at": { "$ref": "#/components/schemas/Timestamp", "description": "When this message entered Norbelys's history." }, "direction": { "$ref": "#/components/schemas/Direction", "description": "The source of this message." }, "from_email": { "description": "The sender's address.", "type": "string" }, "id": { "$ref": "#/components/schemas/MailId", "description": "The original message id, either msg_ or inb_." }, "subject": { "description": "The decoded subject.", "type": "string" }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread", "description": "The correlated conversation; absent for unmatched inbound mail." }, { "type": "null" } ] }, "truncated": { "description": "True when retained MIME or its published attachment list is incomplete.", "type": "boolean" } }, "required": [ "id", "direction", "connection_id", "subject", "from_email", "created_at", "truncated" ], "type": "object" }, "HoldObject": { "description": "A temporary pause of one recipient of a message.", "properties": { "email": { "type": "string" }, "observed_at": { "$ref": "#/components/schemas/Timestamp" }, "reason": { "$ref": "#/components/schemas/HoldReason", "description": "Why the recipient is held; `invalid_recipient` is a reported invalid address waiting for a\nperson's review. New values may be added." }, "resolution": { "oneOf": [ { "$ref": "#/components/schemas/HoldResolution", "description": "How the hold ended; null while it holds. New values may be added." }, { "type": "null" } ] }, "resolved_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "review_after": { "$ref": "#/components/schemas/Timestamp", "description": "When the hold is checked again." } }, "required": [ "email", "reason", "observed_at", "review_after" ], "type": "object" }, "HoldReason": { "description": "Why an address is held (`recipient_holds.reason`).", "enum": [ "mailbox_full", "greylisted", "no_route", "invalid_recipient" ], "type": "string", "x-open-enum": true }, "HoldResolution": { "description": "How a hold ended (`recipient_holds.resolution`): a later success of the message lifted it,\nits time ran out, the address was suppressed, or a person released it. The holds are written\nby the delivery paths in SQL; this is their vocabulary as the API shows it.", "enum": [ "delivered", "expired", "suppressed", "manual" ], "type": "string", "x-open-enum": true }, "HoldSummary": { "description": "An active hold, as preflight shows it: the most recent of the address's holds.", "properties": { "reason": { "$ref": "#/components/schemas/HoldReason", "description": "Why the address is held; `invalid_recipient` is a reported invalid address waiting for a\nperson's review. New values may be added." }, "review_after": { "$ref": "#/components/schemas/Timestamp", "description": "When the hold is checked again." } }, "required": [ "reason", "review_after" ], "type": "object" }, "Id_Attachment": { "examples": [ "fil_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^fil_[0-9a-f]{32}$", "type": "string" }, "Id_Attempt": { "examples": [ "att_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^att_[0-9a-f]{32}$", "type": "string" }, "Id_Campaign": { "examples": [ "cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^cmp_[0-9a-f]{32}$", "type": "string" }, "Id_Connection": { "examples": [ "con_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^con_[0-9a-f]{32}$", "type": "string" }, "Id_DeliveryEvent": { "examples": [ "dev_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^dev_[0-9a-f]{32}$", "type": "string" }, "Id_Enrollment": { "examples": [ "enr_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^enr_[0-9a-f]{32}$", "type": "string" }, "Id_Export": { "examples": [ "exp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^exp_[0-9a-f]{32}$", "type": "string" }, "Id_Field": { "examples": [ "fld_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^fld_[0-9a-f]{32}$", "type": "string" }, "Id_Group": { "examples": [ "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^grp_[0-9a-f]{32}$", "type": "string" }, "Id_Image": { "examples": [ "img_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^img_[0-9a-f]{32}$", "type": "string" }, "Id_Import": { "examples": [ "imp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^imp_[0-9a-f]{32}$", "type": "string" }, "Id_InboundMessage": { "examples": [ "inb_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^inb_[0-9a-f]{32}$", "type": "string" }, "Id_Job": { "examples": [ "job_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^job_[0-9a-f]{32}$", "type": "string" }, "Id_Message": { "examples": [ "msg_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^msg_[0-9a-f]{32}$", "type": "string" }, "Id_OutboxEvent": { "examples": [ "evt_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^evt_[0-9a-f]{32}$", "type": "string" }, "Id_Person": { "examples": [ "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^per_[0-9a-f]{32}$", "type": "string" }, "Id_ProviderWebhook": { "examples": [ "pwh_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^pwh_[0-9a-f]{32}$", "type": "string" }, "Id_QuotaScope": { "examples": [ "qsc_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^qsc_[0-9a-f]{32}$", "type": "string" }, "Id_ReceiveBinding": { "examples": [ "rcv_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^rcv_[0-9a-f]{32}$", "type": "string" }, "Id_Segment": { "examples": [ "seg_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^seg_[0-9a-f]{32}$", "type": "string" }, "Id_SenderIdentity": { "examples": [ "sid_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^sid_[0-9a-f]{32}$", "type": "string" }, "Id_SendingDomain": { "examples": [ "dom_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^dom_[0-9a-f]{32}$", "type": "string" }, "Id_Step": { "examples": [ "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^stp_[0-9a-f]{32}$", "type": "string" }, "Id_Suppression": { "examples": [ "sup_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^sup_[0-9a-f]{32}$", "type": "string" }, "Id_Thread": { "examples": [ "thr_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^thr_[0-9a-f]{32}$", "type": "string" }, "Id_Variant": { "examples": [ "var_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^var_[0-9a-f]{32}$", "type": "string" }, "Id_WebhookDelivery": { "examples": [ "whd_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^whd_[0-9a-f]{32}$", "type": "string" }, "Id_WebhookEndpoint": { "examples": [ "whe_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^whe_[0-9a-f]{32}$", "type": "string" }, "Id_Workspace": { "examples": [ "ws_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ], "pattern": "^ws_[0-9a-f]{32}$", "type": "string" }, "IdentityInput": { "additionalProperties": false, "description": "An identity in a request: without `id` it is added; with the `id` of one of the\nconnection's identities, that one is updated.", "properties": { "email": { "description": "The From address.", "format": "email", "type": "string" }, "enabled": { "description": "Whether campaigns may send from it (default true).", "type": [ "boolean", "null" ] }, "id": { "description": "The identity to update (`sid_…`); absent for a new one.", "type": [ "string", "null" ] }, "name": { "description": "The display name, 1 to 200 characters.", "type": [ "string", "null" ] }, "reply_to": { "description": "The `Reply-To` address.", "format": "email", "type": [ "string", "null" ] }, "signature_html": { "description": "The signature that ends the HTML part of its mail, at most 64 KiB. Set one or both: when\nonly one is set, the other part's signature is derived from it (the HTML's plain text, or\nthe text with its line breaks kept).", "type": [ "string", "null" ] }, "signature_text": { "description": "The signature that ends the text part of its mail, at most 64 KiB. Set one or both: when\nonly one is set, the other part's signature is derived from it (the HTML's plain text, or\nthe text with its line breaks kept).", "type": [ "string", "null" ] }, "tags": { "description": "Up to 20 tags of 1 to 64 characters.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "verified": { "description": "The person attests the address may be sent as (default false); a Gmail mailbox's check\nreplaces it with what Gmail says.", "type": [ "boolean", "null" ] } }, "required": [ "email" ], "type": "object" }, "IdentityObject": { "description": "A sender identity as the API shows it, inside its connection.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "description": "The From address.", "type": "string" }, "enabled": { "description": "Whether campaigns may send from it.", "type": "boolean" }, "id": { "$ref": "#/components/schemas/Id_SenderIdentity" }, "name": { "description": "The display name.", "type": [ "string", "null" ] }, "reply_to": { "description": "The `Reply-To` address.", "type": [ "string", "null" ] }, "signature_html": { "description": "The signature that ends the HTML part of its mail. Set one or both: when only one is set,\nthe other part's signature is derived from it.", "type": [ "string", "null" ] }, "signature_text": { "description": "The signature that ends the text part of its mail. Set one or both: when only one is set,\nthe other part's signature is derived from it.", "type": [ "string", "null" ] }, "tags": { "description": "Tags a campaign selects senders by.", "items": { "type": "string" }, "type": "array" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "verified": { "description": "Whether the address may be sent as: confirmed by the provider where it can say, else the\nperson's word.", "type": "boolean" } }, "required": [ "id", "email", "tags", "enabled", "verified", "created_at", "updated_at" ], "type": "object" }, "ImageContentType": { "description": "An accepted image format. On the wire it is its media type (`image/png`, `image/jpeg`,\n`image/gif`, `image/webp`): what an upload's `Content-Type` names and an image's\n`content_type` shows.", "enum": [ "image/png", "image/jpeg", "image/gif", "image/webp" ], "type": "string", "x-open-enum": true }, "ImageObject": { "description": "An image as the API shows it.", "properties": { "content_type": { "$ref": "#/components/schemas/ImageContentType", "description": "The image's media type. New values may be added." }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Image" }, "size": { "description": "The file's size in bytes.", "format": "int32", "type": "integer" }, "url": { "description": "Where anyone fetches the image: the address to put in a message's HTML.", "type": "string" } }, "required": [ "id", "url", "content_type", "size", "created_at" ], "type": "object" }, "ImapInput": { "additionalProperties": false, "description": "An IMAP endpoint, as a request gives it; it logs in with the SMTP login and password.", "properties": { "host": { "description": "The host name.", "type": "string" }, "port": { "description": "The port.", "format": "int32", "minimum": 0, "type": "integer" }, "security": { "$ref": "#/components/schemas/ImapSecurity", "description": "`tls` (993), or `plain` (a private host in development only)." } }, "required": [ "host", "port", "security" ], "type": "object" }, "ImapSecurity": { "description": "How an IMAP session is secured.", "enum": [ "tls", "plain" ], "type": "string", "x-open-enum": true }, "ImapSettings": { "description": "An IMAP endpoint, as stored in `connections.imap` and shown; it logs in with the SMTP login\nand password.", "properties": { "host": { "description": "The host name.", "type": "string" }, "port": { "description": "The port.", "format": "int32", "minimum": 0, "type": "integer" }, "security": { "$ref": "#/components/schemas/ImapSecurity", "description": "How the session is secured." } }, "required": [ "host", "port", "security" ], "type": "object" }, "ImportCounts": { "description": "An import's rows so far.", "properties": { "imported": { "description": "Rows that created a person or merged into one.", "format": "int64", "type": "integer" }, "invalid": { "description": "Rows that could not describe a person.", "format": "int64", "type": "integer" }, "skipped": { "description": "Rows whose address an earlier row of the file already imported.", "format": "int64", "type": "integer" }, "total": { "description": "Rows read.", "format": "int64", "type": "integer" } }, "required": [ "total", "imported", "skipped", "invalid" ], "type": "object" }, "ImportErrors": { "description": "An import's problems: a first page and the report.", "properties": { "data": { "description": "One problem per invalid row, the first 100.", "items": { "$ref": "#/components/schemas/RowProblem" }, "maxItems": 100, "type": "array" }, "has_more": { "description": "True when more rows are invalid than `data` shows.", "type": "boolean" }, "url": { "description": "A CSV of every problem of every invalid row (`row,field,problem`), once the import\ncompleted; the link works for 15 minutes from this read.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ], "type": "object" }, "ImportFormat": { "description": "The format of an import's file: what an import read, a CSV file or the people of a JSON body.", "enum": [ "csv", "json" ], "type": "string", "x-open-enum": true }, "ImportObject": { "description": "An import as the API shows it.", "properties": { "completed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "counts": { "$ref": "#/components/schemas/ImportCounts" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "errors": { "$ref": "#/components/schemas/ImportErrors", "description": "The first 100 problems, one per invalid row, and a link to the full report." }, "format": { "$ref": "#/components/schemas/ImportFormat", "description": "What it read." }, "group_id": { "description": "The group every imported person joins.", "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/Id_Import" }, "job_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Job", "description": "The job doing the work." }, { "type": "null" } ] }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "Why the import failed." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ImportStatus", "description": "Where the import is. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "id", "status", "format", "counts", "errors", "created_at", "updated_at" ], "type": "object" }, "ImportStatus": { "description": "Where an import is (`imports.status`): `queued` until its job starts, `processing` while it\nreads rows, then `completed` (invalid rows are reported, not fatal) or `failed`.", "enum": [ "queued", "processing", "completed", "failed" ], "type": "string", "x-open-enum": true }, "InboundClassification": { "description": "An inbound message's classification (`inbound_messages.classification`).", "enum": [ "human_reply", "auto_reply", "out_of_office", "bounce", "complaint", "address_change", "unsubscribe", "unknown" ], "type": "string", "x-open-enum": true }, "InboundMessageObject": { "description": "A message the inbox read.", "properties": { "classification": { "$ref": "#/components/schemas/InboundClassification" }, "classification_source": { "$ref": "#/components/schemas/ClassificationSource" }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "evidence": { "description": "Which header or field decided the classification.", "type": "string" }, "from": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_InboundMessage" }, "in_reply_to": { "description": "The `Message-ID` it answers.", "type": [ "string", "null" ] }, "internet_message_id": { "description": "Its `Message-ID` header.", "type": [ "string", "null" ] }, "message_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "The outbound message it answers or reports on, when correlated." }, { "type": "null" } ] }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person" }, { "type": "null" } ] }, "received_at": { "$ref": "#/components/schemas/Timestamp" }, "references": { "description": "Its `References`, oldest first.", "items": { "type": "string" }, "type": "array" }, "review": { "$ref": "#/components/schemas/InboundReview" }, "sentiment": { "oneOf": [ { "$ref": "#/components/schemas/Sentiment", "description": "The writer's attitude, when known." }, { "type": "null" } ] }, "size_bytes": { "description": "Its size as the provider reported it.", "format": "int32", "type": [ "integer", "null" ] }, "subject": { "type": [ "string", "null" ] }, "text": { "description": "The start of its text body.", "type": [ "string", "null" ] }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread" }, { "type": "null" } ] }, "truncated": { "description": "It was larger than what the inbox keeps.", "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "connection_id", "references", "truncated", "classification", "classification_source", "evidence", "review", "received_at", "created_at", "updated_at", "version" ], "type": "object" }, "InboundReview": { "description": "Whether a person was asked to decide, what confirming applies, and the decision.", "properties": { "decision": { "oneOf": [ { "$ref": "#/components/schemas/ReviewDecision" }, { "type": "null" } ] }, "proposal": { "oneOf": [ { "$ref": "#/components/schemas/ReviewProposal", "description": "What confirming applies; `null` when confirming only records the decision." }, { "type": "null" } ] }, "requested_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When a rule or the classifier asked for a review; `null` when none was asked." }, { "type": "null" } ] }, "reviewed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] } }, "type": "object" }, "InvalidAddress": { "description": "An entry of `emails` that is not an address.", "properties": { "detail": { "description": "Why it is not an address.", "type": "string" }, "index": { "description": "Its position in `emails`, from 0 (its pointer is `/emails/{index}`).", "minimum": 0, "type": "integer" }, "value": { "description": "The entry as given.", "type": "string" } }, "required": [ "index", "value", "detail" ], "type": "object" }, "JobObject": { "description": "A job as the API shows it.", "properties": { "attempts": { "description": "Failed runs so far; a yield is not a failure.", "format": "int32", "type": "integer" }, "cancel_requested_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When cancellation was requested." }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "finished_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the job reached `completed`, `failed` or `cancelled`." }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_Job" }, "kind": { "description": "The kind of work, such as `enrollment.add`. New kinds may be added.", "type": "string" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "Why the last failed run failed, or why the job ended; null after a success." }, { "type": "null" } ] }, "progress": { "description": "What the job has done so far, as its last checkpoint recorded it." }, "result": { "description": "The job's bounded result, once it completed (at most 64 KiB)." }, "state": { "$ref": "#/components/schemas/JobState", "description": "Where the job is. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "id", "kind", "state", "attempts", "created_at", "updated_at" ], "type": "object" }, "JobState": { "description": "Where a job is (`jobs.state`): `available` while it waits for its run, `running`, then\n`completed`, `failed` or `cancelled`; `needs_review` when an operator decides whether an\nambiguous external effect happened.", "enum": [ "available", "running", "completed", "failed", "cancelled", "needs_review" ], "type": "string", "x-open-enum": true }, "LastAttempt": { "description": "The latest attempt of a delivery.", "properties": { "duration_ms": { "format": "int32", "type": [ "integer", "null" ] }, "response_excerpt": { "description": "The answer's first kilobyte, or what went wrong when nothing was answered.", "type": [ "string", "null" ] }, "response_status": { "description": "The answer's status; null when nothing was answered.", "format": "int32", "type": [ "integer", "null" ] }, "started_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "started_at" ], "type": "object" }, "LastError": { "description": "The last error of a deferred resource. Resources that keep it in a row of their own (imports,\nexports) store this same shape as JSON.", "properties": { "at": { "$ref": "#/components/schemas/Timestamp", "description": "When the job's row last changed: the moment of the error for a job that ended, and at\nor after it while the job is still waiting or running (the row keeps no separate time\nfor its error)." }, "code": { "description": "A short machine-readable code (`error`, `lease_expired`, `unknown_kind`, `cancelled`, …).", "type": "string" }, "detail": { "description": "A human-readable explanation.", "type": "string" } }, "required": [ "code", "detail", "at" ], "type": "object" }, "ListInclude": { "description": "What a list adds to its page's `meta` on request (`?include=`).", "enum": [ "total_count" ], "type": "string" }, "ListOrder": { "description": "The direction of a list's order (`?order=`): `desc`, the default, is newest first under the\n`id` sort.", "enum": [ "desc", "asc" ], "type": "string" }, "MailExchange": { "description": "A published incoming-mail route, including the provider's MX preference.", "properties": { "hostname": { "type": "string" }, "priority": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "hostname", "priority" ], "type": "object" }, "MailId": { "description": "Either typed message id, preserving its resource prefix in a shared history.", "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "A sent or queued message." }, { "$ref": "#/components/schemas/Id_InboundMessage", "description": "A received message." } ] }, "MailboxFinding": { "properties": { "detail": { "description": "A bounded explanation of the SMTP result, or why this check was skipped.", "type": "string" }, "status": { "$ref": "#/components/schemas/MailboxStatus" } }, "required": [ "status", "detail" ], "type": "object" }, "MailboxStatus": { "description": "What the optional SMTP check established; acceptance does not prove delivery or ownership.", "enum": [ "accepted", "invalid", "unknown", "skipped" ], "type": "string", "x-open-enum": true }, "MessageAttempts": { "description": "A message's latest attempts.", "properties": { "data": { "description": "At most 20, newest first.", "items": { "$ref": "#/components/schemas/AttemptObject" }, "maxItems": 20, "type": "array" }, "has_more": { "description": "More attempts exist than `data` shows; read them through an export.", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "MessageContent": { "allOf": [ { "$ref": "#/components/schemas/HistoryMessage", "description": "Message identity and routing metadata." }, { "properties": { "attachments": { "description": "Available files, with expiring download URLs.", "items": { "$ref": "#/components/schemas/AttachmentObject" }, "maxItems": 100, "type": "array" }, "bcc": { "description": "Blind copy addresses visible to this workspace.", "items": { "type": "string" }, "type": "array" }, "cc": { "description": "Copy recipient addresses.", "items": { "type": "string" }, "type": "array" }, "headers": { "description": "MIME header name/value pairs, retaining wire encodings and repeated fields.", "items": { "items": false, "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array" }, "type": "array" }, "html": { "description": "Complete retained HTML, never an excerpt.", "type": [ "string", "null" ] }, "prepared_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The latest composition time; null before outbound rendering or for received content." }, { "type": "null" } ] }, "raw_download_url": { "description": "Five-minute download link for retained received MIME; null for outbound content.", "type": [ "string", "null" ] }, "text": { "description": "Complete retained plain text, never the classification excerpt.", "type": [ "string", "null" ] }, "to": { "description": "Primary recipient addresses.", "items": { "type": "string" }, "type": "array" } }, "required": [ "to", "cc", "bcc", "headers", "attachments" ], "type": "object" } ], "description": "Full retained content, isolated from ordinary list responses." }, "MessageEvents": { "description": "A message's first delivery events.", "properties": { "data": { "description": "At most 20, in the order they were observed.", "items": { "$ref": "#/components/schemas/DeliveryEventObject" }, "maxItems": 20, "type": "array" }, "has_more": { "description": "More events exist; `url` lists them all.", "type": "boolean" }, "url": { "description": "The delivery event list of this message.", "type": "string" } }, "required": [ "data", "has_more", "url" ], "type": "object" }, "MessageForm": { "description": "The forms of `POST /messages`: a direct message, a reply in a thread, or a campaign step's\ncontent for one person or for several. Each form refuses the members it does not name, and any\ntwo forms differ in a member one requires and the other refuses, so a body is one form only.", "oneOf": [ { "$ref": "#/components/schemas/CreateMessage" }, { "$ref": "#/components/schemas/CreateStepMessage" }, { "$ref": "#/components/schemas/CreateStepMessages" }, { "$ref": "#/components/schemas/CreateReply" } ] }, "MessageKind": { "description": "What a message is, as `messages.kind` stores it.", "enum": [ "campaign", "direct", "reply", "transactional" ], "type": "string", "x-open-enum": true }, "MessageObject": { "description": "A message as the API shows it.", "properties": { "attempts": { "$ref": "#/components/schemas/MessageAttempts" }, "attempts_count": { "description": "Every attempt it had.", "format": "int64", "type": "integer" }, "bcc": { "items": { "type": "string" }, "type": "array" }, "campaign_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Campaign" }, { "type": "null" } ] }, "cc": { "items": { "type": "string" }, "type": "array" }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "enrollment_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Enrollment" }, { "type": "null" } ] }, "events": { "$ref": "#/components/schemas/MessageEvents" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When it stops being useful, while it waits to be sent." }, { "type": "null" } ] }, "from": { "$ref": "#/components/schemas/Address" }, "holds": { "description": "One per held recipient: at most the 150 addresses of the envelope.", "items": { "$ref": "#/components/schemas/HoldObject" }, "maxItems": 150, "type": "array" }, "id": { "$ref": "#/components/schemas/Id_Message" }, "in_reply_to": { "description": "The `Message-ID` it answers.", "type": [ "string", "null" ] }, "internet_message_id": { "description": "The `Message-ID` header.", "type": "string" }, "kind": { "$ref": "#/components/schemas/MessageKind", "description": "What the message is. New values may be added." }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person" }, { "type": "null" } ] }, "reply_to": { "type": [ "string", "null" ] }, "send_at": { "$ref": "#/components/schemas/Timestamp", "description": "When it is due." }, "sender_identity_id": { "$ref": "#/components/schemas/Id_SenderIdentity" }, "sent_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When a provider accepted it." }, { "type": "null" } ] }, "snippets_fallback": { "oneOf": [ { "$ref": "#/components/schemas/SnippetsFallback", "description": "For a campaign step message whose step asks for personalisation snippets that were not\nwritten: why; its template's defaults were used instead. `null` otherwise. New values may\nbe added." }, { "type": "null" } ] }, "state": { "$ref": "#/components/schemas/MessageState", "description": "Where the message is in its life: `queued`, `claimed` and `in_flight` are live, the others\nfinal. New values may be added." }, "status_detail": { "description": "Why it is in its state, when that needs words.", "type": [ "string", "null" ] }, "step_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Step" }, { "type": "null" } ] }, "subject": { "description": "The subject as sent.", "type": "string" }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread" }, { "type": "null" } ] }, "to": { "items": { "type": "string" }, "type": "array" }, "tracking": { "$ref": "#/components/schemas/Tracking" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "variant_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Variant" }, { "type": "null" } ] } }, "required": [ "id", "kind", "state", "from", "to", "cc", "bcc", "subject", "connection_id", "sender_identity_id", "internet_message_id", "tracking", "send_at", "created_at", "updated_at", "attempts", "attempts_count", "events", "holds" ], "type": "object" }, "MessageState": { "description": "Where a message is in its life, as `messages.state` stores it. `queued`, `claimed` and\n`in_flight` are live (the message has a row in the delivery queue); the others are final.", "enum": [ "queued", "claimed", "in_flight", "sent", "failed", "cancelled", "uncertain", "suppressed" ], "type": "string", "x-open-enum": true }, "MessagesCreated": { "description": "What `POST /messages` answers: the message, or, for `person_ids`, a result per person. The\noperation's `x-norbelys-overloads` says which form receives which.", "oneOf": [ { "$ref": "#/components/schemas/MessageObject" }, { "$ref": "#/components/schemas/StepResults" } ] }, "Meta": { "description": "The page metadata.", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total_count": { "description": "With `?include=total_count`: exact up to 10,000.", "format": "int64", "type": [ "integer", "null" ] }, "total_count_capped": { "description": "With `?include=total_count`: true when the count stopped at 10,000.", "type": [ "boolean", "null" ] } }, "required": [ "has_more" ], "type": "object" }, "Metered": { "description": "A count and the limit it is held to; `limit` is `null` when nothing limits it.", "properties": { "limit": { "format": "int64", "type": [ "integer", "null" ] }, "used": { "format": "int64", "type": "integer" } }, "required": [ "used" ], "type": "object" }, "MetricDay": { "description": "Daily event history, retained independently of the message rows.", "properties": { "counters": { "$ref": "#/components/schemas/Counters", "description": "Counters for the requested filters." }, "day": { "$ref": "#/components/schemas/Date", "description": "UTC day when the events were recorded." } }, "required": [ "day", "counters" ], "type": "object" }, "Metrics": { "description": "Counts and optional rates for a range, or current workspace usage.", "oneOf": [ { "description": "Daily delivery and engagement, across all message kinds by default.", "properties": { "computed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "How far the rollup has processed; null before its first run." }, { "type": "null" } ] }, "data": { "description": "Daily counts, at most 366 entries.", "items": { "$ref": "#/components/schemas/MetricDay" }, "maxItems": 366, "type": "array" }, "family": { "$ref": "#/components/schemas/Family", "description": "The requested family: events or rates." }, "from": { "$ref": "#/components/schemas/Date", "description": "Inclusive first UTC day." }, "rates": { "oneOf": [ { "$ref": "#/components/schemas/Rates", "description": "Present only for the rates family; values are per 10,000 sends." }, { "type": "null" } ] }, "to": { "$ref": "#/components/schemas/Date", "description": "Inclusive last UTC day." }, "totals": { "$ref": "#/components/schemas/Counters", "description": "Counts over the whole range." } }, "required": [ "family", "from", "to", "totals", "data" ], "type": "object" }, { "description": "Current-month usage without historical filters.", "properties": { "family": { "$ref": "#/components/schemas/Family", "description": "Always usage." }, "usage": { "$ref": "#/components/schemas/WorkspaceUsage", "description": "The same usage visible on the workspace resource." } }, "required": [ "family", "usage" ], "type": "object" } ] }, "Objective": { "description": "What a test of variants is decided by (`step_revisions.ranking_objective`).", "enum": [ "opens", "clicks", "replies" ], "type": "string", "x-open-enum": true }, "OnSenderRemoved": { "description": "What a campaign does with a conversation whose sender left its pool\n(`campaigns.on_sender_removed`).", "enum": [ "reassign", "stop" ], "type": "string", "x-open-enum": true }, "Operator": { "description": "How a condition compares.", "enum": [ "equals", "not_equals", "in", "starts_with", "exists", "not_exists", "gt", "gte", "lt", "lte" ], "type": "string", "x-open-enum": true }, "Page_CampaignObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A campaign as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "enrollments": { "oneOf": [ { "$ref": "#/components/schemas/EnrollmentSummary", "description": "Where the campaign's people are now and when its next email may go, counted whenever one\ncampaign is answered (retrieved, created, updated, started, paused, or archived by a\ndeletion); `null` in a list. Like `stats`, it is not part of `version`." }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_Campaign" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/CampaignLastError", "description": "Why the campaign cannot send right now, while that lasts: `no_sender` (no sender of the\npool is usable; its conversations wait and continue by themselves), `invalid` (it could\nnot start)." }, { "type": "null" } ] }, "name": { "type": "string" }, "schedule": { "$ref": "#/components/schemas/ScheduleObject" }, "senders": { "$ref": "#/components/schemas/SendersObject" }, "stats": { "$ref": "#/components/schemas/StatsObject" }, "status": { "$ref": "#/components/schemas/CampaignStatus" }, "steps": { "description": "The steps in order, with their variants (a list leaves out the variants' bodies).", "items": { "$ref": "#/components/schemas/StepObject" }, "maxItems": 50, "type": "array" }, "stop_rules": { "$ref": "#/components/schemas/StopRulesObject" }, "tracking": { "$ref": "#/components/schemas/TrackingObject" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The version an update's `If-Match` names.", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "status", "steps", "senders", "schedule", "tracking", "stop_rules", "stats", "version", "created_at", "updated_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_ConnectionObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A connection as the API shows it.", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "authorization": { "oneOf": [ { "$ref": "#/components/schemas/Authorization", "description": "Present when the browser must give consent first." }, { "type": "null" } ] }, "checked_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The last check of the credential." }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "created_by": { "type": [ "string", "null" ] }, "daily_limit": { "description": "Submissions a UTC day.", "format": "int32", "type": "integer" }, "id": { "$ref": "#/components/schemas/Id_Connection" }, "identities": { "description": "The service's sender addresses.", "items": { "$ref": "#/components/schemas/IdentityObject" }, "maxItems": 1000, "type": "array" }, "imap": { "oneOf": [ { "$ref": "#/components/schemas/ImapSettings", "description": "The IMAP endpoint of an SMTP login." }, { "type": "null" } ] }, "paused": { "description": "The person's pause: sending stops, conversations wait.", "type": "boolean" }, "paused_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The breaker holds the connection until then." }, { "type": "null" } ] }, "provider": { "$ref": "#/components/schemas/Provider", "description": "The provider of the account; new values may be added." }, "quota_scope_id": { "type": [ "string", "null" ] }, "receiving": { "$ref": "#/components/schemas/ReceivingObject", "description": "The folders read, at most 10." }, "send_interval_minutes": { "description": "Minutes between campaign emails: exact whole minutes for Norbelys, 5-minute slots for mailboxes and SES; null when rate-paced.", "format": "int32", "type": [ "integer", "null" ] }, "send_window": { "oneOf": [ { "$ref": "#/components/schemas/SendWindow", "description": "When campaign mail may be submitted, in `timezone`." }, { "type": "null" } ] }, "smtp": { "oneOf": [ { "$ref": "#/components/schemas/SmtpSettings", "description": "The SMTP endpoint (relays, SMTP logins, the managed MTA)." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ConnectionStatus", "description": "Its health: `active` sends (unless `paused`), `authorization_required` waits for a new\ncredential or consent, `archived` ended. New values may be added." }, "status_detail": { "description": "The health text: what went wrong and what to do.", "type": [ "string", "null" ] }, "timezone": { "description": "The IANA time zone of the send window.", "type": "string" }, "transport": { "$ref": "#/components/schemas/Transport", "description": "What it submits over: SMTP, or the Gmail API or Microsoft Graph (`api`)." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "usage": { "$ref": "#/components/schemas/Usage" }, "version": { "description": "The connection's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplacement of `identities` or of the folders read never undoes a change made since it\nwas read. Health checks and the sender's pacing move it too.", "format": "int64", "type": "integer" }, "warmup_stage": { "description": "The warm-up stage; null when not warming.", "format": "int32", "type": [ "integer", "null" ] }, "webhook": { "oneOf": [ { "$ref": "#/components/schemas/WebhookObject", "description": "A relay's or the managed MTA's provider webhook." }, { "type": "null" } ] } }, "required": [ "id", "provider", "transport", "account", "status", "paused", "identities", "receiving", "daily_limit", "timezone", "usage", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_DeliveryEventObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "One observation about a message's fate.", "properties": { "action": { "oneOf": [ { "$ref": "#/components/schemas/DsnAction", "description": "The RFC 3464 action, for a delivery status notification." }, { "type": "null" } ] }, "attempt_number": { "description": "The attempt it comes from, when its source is an attempt.", "format": "int32", "type": [ "integer", "null" ] }, "category": { "$ref": "#/components/schemas/EvidenceCategory", "description": "Why it happened, in the closed vocabulary of evidence. New values may be added." }, "confidence": { "$ref": "#/components/schemas/EvidenceConfidence", "description": "How far the observation can be trusted. New values may be added." }, "diagnostic": { "type": [ "string", "null" ] }, "enhanced_status": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/Id_DeliveryEvent" }, "kind": { "$ref": "#/components/schemas/DeliveryEventKind", "description": "What was observed. New values may be added." }, "message_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "The message, when the evidence could be matched to one." }, { "type": "null" } ] }, "observed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the source observed it." }, "phase": { "oneOf": [ { "$ref": "#/components/schemas/SubmissionPhase", "description": "The protocol step a submission's answer came from, for the `smtp` and `provider_api`\nsources." }, { "type": "null" } ] }, "processed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When Norbelys recorded it." }, "provider_code": { "description": "An exact provider-specific rejection code found in `diagnostic`, when any; it does not\nchange the event's kind, recipient effect, or retry decision.", "type": [ "string", "null" ] }, "received_at": { "$ref": "#/components/schemas/Timestamp", "description": "When Norbelys received it." }, "recipient": { "description": "The recipient it concerns; null when the evidence names none.", "type": [ "string", "null" ] }, "recipient_ref": { "$ref": "#/components/schemas/RecipientRef", "description": "Why the recipient is known. New values may be added." }, "source": { "$ref": "#/components/schemas/EvidenceSource", "description": "Where the observation came from. New values may be added." }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread" }, { "type": "null" } ] } }, "required": [ "id", "kind", "source", "confidence", "recipient_ref", "category", "observed_at", "received_at", "processed_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_DeliveryObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A delivery as the API shows it.", "properties": { "attempts": { "description": "Attempts made so far.", "format": "int32", "type": "integer" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "delivered_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "event_id": { "$ref": "#/components/schemas/Id_OutboxEvent" }, "event_type": { "$ref": "#/components/schemas/EventType", "description": "The event's type." }, "id": { "$ref": "#/components/schemas/Id_WebhookDelivery" }, "last_attempt": { "oneOf": [ { "$ref": "#/components/schemas/LastAttempt", "description": "The latest attempt, failures included." }, { "type": "null" } ] }, "next_attempt_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the next attempt is due, while `pending`." }, { "type": "null" } ] }, "state": { "$ref": "#/components/schemas/WebhookDeliveryState", "description": "Where the delivery is. New values may be added." }, "webhook_endpoint_id": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } }, "required": [ "id", "event_id", "event_type", "webhook_endpoint_id", "state", "attempts", "created_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_DomainObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A sending domain as the API shows it.", "properties": { "checked_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "dns_preparation": { "$ref": "#/components/schemas/DnsPreparation", "description": "Whether publication instructions are being prepared, ready, or unavailable on this installation." }, "existing_mx": { "description": "Existing MX targets discovered during DNS preparation or verification.", "items": { "$ref": "#/components/schemas/MailExchange" }, "maxItems": 64, "type": "array" }, "hostname": { "description": "The hostname, lowercase.", "type": "string" }, "id": { "$ref": "#/components/schemas/Id_SendingDomain" }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "What the last check found wrong." }, { "type": "null" } ] }, "purpose": { "$ref": "#/components/schemas/DomainPurpose", "description": "The intended use of this hostname; mail and CNAME tracking use separate names." }, "records": { "description": "The records to publish: the ownership TXT record, the tracking CNAME when the hostname\nserves tracking links, and the managed MTA's SPF, DMARC and DKIM records once rendered.\nSPF and DMARC are publication instructions and remain `unchecked`.", "items": { "$ref": "#/components/schemas/DnsRecord" }, "maxItems": 5, "type": "array" }, "status": { "$ref": "#/components/schemas/SendingDomainStatus", "description": "Where the domain is in its lifecycle; new values may be added." }, "tracking_domain": { "oneOf": [ { "$ref": "#/components/schemas/TrackingDomainObject", "description": "Optional custom tracking hosted at another hostname." }, { "type": "null" } ] }, "tracking_enabled": { "description": "Whether the hostname serves tracking links.", "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "verified_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "version": { "description": "The domain's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version. Each DNS\ncheck moves it too.", "format": "int64", "type": "integer" }, "warnings": { "description": "Existing-provider and DNS conflict advice; no existing DNS record is changed by the API.", "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "hostname", "status", "tracking_enabled", "purpose", "dns_preparation", "existing_mx", "warnings", "records", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_EndpointObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "An endpoint as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "disabled_reason": { "oneOf": [ { "$ref": "#/components/schemas/EndpointDisabledReason", "description": "Why it was disabled: it answered `410` (`gone`), it failed for 5 days without a success\n(`failing`), or a person disabled it (`manual`). Null while enabled. New values may be added." }, { "type": "null" } ] }, "enabled": { "description": "False once disabled, by a person or by its failures.", "type": "boolean" }, "event_types": { "description": "The event types the endpoint receives.", "items": { "$ref": "#/components/schemas/EventType" }, "type": "array" }, "failing_since": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The first failed attempt since the last success." }, { "type": "null" } ] }, "filters": { "$ref": "#/components/schemas/Filters", "description": "Resource filters applied together with the event types." }, "header_names": { "description": "Configured header names; their values are never returned.", "items": { "type": "string" }, "type": "array" }, "id": { "$ref": "#/components/schemas/Id_WebhookEndpoint" }, "secret": { "description": "The signing secret, shown only when the endpoint is created or its secret rotated.", "type": [ "string", "null" ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "url": { "type": "string" }, "version": { "description": "The endpoint's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplaced list of event types never undoes a change made since it was read. A failure or\na disabling by the worker moves it too.", "format": "int64", "type": "integer" } }, "required": [ "id", "url", "event_types", "filters", "header_names", "enabled", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_EnrollmentObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "An enrollment as the API shows it.", "properties": { "campaign_id": { "$ref": "#/components/schemas/Id_Campaign" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Enrollment" }, "message_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "The current step's message, while it is on its way." }, { "type": "null" } ] }, "next_run_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When its current step is due; `null` while the step's message is on its way, or once\nit ended." }, { "type": "null" } ] }, "person": { "$ref": "#/components/schemas/PersonRef" }, "position": { "description": "The step it is at, 1 for the first.", "format": "int32", "type": "integer" }, "sender_identity_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_SenderIdentity", "description": "The sender its conversation keeps, once one was assigned." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/EnrollmentStatus" }, "status_detail": { "description": "Why it ended, when it ended early.", "type": [ "string", "null" ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "waiting_for": { "oneOf": [ { "$ref": "#/components/schemas/Id_SenderIdentity", "description": "The sender the next step waits for, while that sender is unavailable." }, { "type": "null" } ] } }, "required": [ "id", "campaign_id", "person", "status", "position", "created_at", "updated_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_EventObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "An event as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "data": { "description": "What consumers receive." }, "id": { "$ref": "#/components/schemas/Id_OutboxEvent" }, "synthetic": { "description": "True for an event created on request (`POST /events`) rather than by a real change.", "type": "boolean" }, "type": { "$ref": "#/components/schemas/EventType", "description": "The event's type, such as `message.sent`. New types may be added." }, "webhook_endpoint_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_WebhookEndpoint", "description": "The one endpoint a synthetic event is addressed to, if any." }, { "type": "null" } ] } }, "required": [ "id", "type", "data", "synthetic", "created_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_ExportObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "An export as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "expires_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the file is deleted." }, "filters": { "description": "The filters of the resource's list the file applies.", "type": "object" }, "format": { "$ref": "#/components/schemas/ExportFormat", "description": "The file's format." }, "id": { "$ref": "#/components/schemas/Id_Export" }, "job_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Job", "description": "The job doing the work." }, { "type": "null" } ] }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "Why the export failed." }, { "type": "null" } ] }, "resource": { "$ref": "#/components/schemas/ExportResource", "description": "What the file contains. New values may be added." }, "rows": { "description": "The rows in the file, once it is ready.", "format": "int64", "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/ExportStatus", "description": "Where the export is. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "url": { "description": "The file, when `ready`: a link that works for 15 minutes from this read.", "type": [ "string", "null" ] } }, "required": [ "id", "resource", "filters", "format", "status", "expires_at", "created_at", "updated_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_FieldObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A custom field definition as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Field" }, "key": { "description": "How values are stored in a person's `fields` and named in imports and segments.", "type": "string" }, "label": { "description": "The name people read.", "type": "string" }, "options": { "description": "An enum field's allowed values; empty for every other type.", "items": { "type": "string" }, "type": "array" }, "type": { "$ref": "#/components/schemas/FieldType", "description": "What its values are. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The field's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplacement of `options` never undoes a change made since it was read.", "format": "int64", "type": "integer" } }, "required": [ "id", "key", "label", "type", "options", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_GroupObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A group as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "description": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/Id_Group" }, "name": { "type": "string" }, "people_count": { "description": "The people in the group, counted now; not part of `version`, since no update writes it.", "format": "int64", "type": "integer" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The group's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version.", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "people_count", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_HistoryMessage": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "One result in ingestion order, with no large bodies or download links.", "properties": { "connection_id": { "$ref": "#/components/schemas/Id_Connection", "description": "The connection used to send or receive it." }, "created_at": { "$ref": "#/components/schemas/Timestamp", "description": "When this message entered Norbelys's history." }, "direction": { "$ref": "#/components/schemas/Direction", "description": "The source of this message." }, "from_email": { "description": "The sender's address.", "type": "string" }, "id": { "$ref": "#/components/schemas/MailId", "description": "The original message id, either msg_ or inb_." }, "subject": { "description": "The decoded subject.", "type": "string" }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread", "description": "The correlated conversation; absent for unmatched inbound mail." }, { "type": "null" } ] }, "truncated": { "description": "True when retained MIME or its published attachment list is incomplete.", "type": "boolean" } }, "required": [ "id", "direction", "connection_id", "subject", "from_email", "created_at", "truncated" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_ImportObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "An import as the API shows it.", "properties": { "completed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "counts": { "$ref": "#/components/schemas/ImportCounts" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "errors": { "$ref": "#/components/schemas/ImportErrors", "description": "The first 100 problems, one per invalid row, and a link to the full report." }, "format": { "$ref": "#/components/schemas/ImportFormat", "description": "What it read." }, "group_id": { "description": "The group every imported person joins.", "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/Id_Import" }, "job_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Job", "description": "The job doing the work." }, { "type": "null" } ] }, "last_error": { "oneOf": [ { "$ref": "#/components/schemas/LastError", "description": "Why the import failed." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ImportStatus", "description": "Where the import is. New values may be added." }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "id", "status", "format", "counts", "errors", "created_at", "updated_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_InboundMessageObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A message the inbox read.", "properties": { "classification": { "$ref": "#/components/schemas/InboundClassification" }, "classification_source": { "$ref": "#/components/schemas/ClassificationSource" }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "evidence": { "description": "Which header or field decided the classification.", "type": "string" }, "from": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_InboundMessage" }, "in_reply_to": { "description": "The `Message-ID` it answers.", "type": [ "string", "null" ] }, "internet_message_id": { "description": "Its `Message-ID` header.", "type": [ "string", "null" ] }, "message_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Message", "description": "The outbound message it answers or reports on, when correlated." }, { "type": "null" } ] }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person" }, { "type": "null" } ] }, "received_at": { "$ref": "#/components/schemas/Timestamp" }, "references": { "description": "Its `References`, oldest first.", "items": { "type": "string" }, "type": "array" }, "review": { "$ref": "#/components/schemas/InboundReview" }, "sentiment": { "oneOf": [ { "$ref": "#/components/schemas/Sentiment", "description": "The writer's attitude, when known." }, { "type": "null" } ] }, "size_bytes": { "description": "Its size as the provider reported it.", "format": "int32", "type": [ "integer", "null" ] }, "subject": { "type": [ "string", "null" ] }, "text": { "description": "The start of its text body.", "type": [ "string", "null" ] }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread" }, { "type": "null" } ] }, "truncated": { "description": "It was larger than what the inbox keeps.", "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "connection_id", "references", "truncated", "classification", "classification_source", "evidence", "review", "received_at", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_MessageObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A message as the API shows it.", "properties": { "attempts": { "$ref": "#/components/schemas/MessageAttempts" }, "attempts_count": { "description": "Every attempt it had.", "format": "int64", "type": "integer" }, "bcc": { "items": { "type": "string" }, "type": "array" }, "campaign_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Campaign" }, { "type": "null" } ] }, "cc": { "items": { "type": "string" }, "type": "array" }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "enrollment_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Enrollment" }, { "type": "null" } ] }, "events": { "$ref": "#/components/schemas/MessageEvents" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When it stops being useful, while it waits to be sent." }, { "type": "null" } ] }, "from": { "$ref": "#/components/schemas/Address" }, "holds": { "description": "One per held recipient: at most the 150 addresses of the envelope.", "items": { "$ref": "#/components/schemas/HoldObject" }, "maxItems": 150, "type": "array" }, "id": { "$ref": "#/components/schemas/Id_Message" }, "in_reply_to": { "description": "The `Message-ID` it answers.", "type": [ "string", "null" ] }, "internet_message_id": { "description": "The `Message-ID` header.", "type": "string" }, "kind": { "$ref": "#/components/schemas/MessageKind", "description": "What the message is. New values may be added." }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person" }, { "type": "null" } ] }, "reply_to": { "type": [ "string", "null" ] }, "send_at": { "$ref": "#/components/schemas/Timestamp", "description": "When it is due." }, "sender_identity_id": { "$ref": "#/components/schemas/Id_SenderIdentity" }, "sent_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When a provider accepted it." }, { "type": "null" } ] }, "snippets_fallback": { "oneOf": [ { "$ref": "#/components/schemas/SnippetsFallback", "description": "For a campaign step message whose step asks for personalisation snippets that were not\nwritten: why; its template's defaults were used instead. `null` otherwise. New values may\nbe added." }, { "type": "null" } ] }, "state": { "$ref": "#/components/schemas/MessageState", "description": "Where the message is in its life: `queued`, `claimed` and `in_flight` are live, the others\nfinal. New values may be added." }, "status_detail": { "description": "Why it is in its state, when that needs words.", "type": [ "string", "null" ] }, "step_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Step" }, { "type": "null" } ] }, "subject": { "description": "The subject as sent.", "type": "string" }, "thread_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Thread" }, { "type": "null" } ] }, "to": { "items": { "type": "string" }, "type": "array" }, "tracking": { "$ref": "#/components/schemas/Tracking" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "variant_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Variant" }, { "type": "null" } ] } }, "required": [ "id", "kind", "state", "from", "to", "cc", "bcc", "subject", "connection_id", "sender_identity_id", "internet_message_id", "tracking", "send_at", "created_at", "updated_at", "attempts", "attempts_count", "events", "holds" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_PersonObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A person as the API shows it.", "properties": { "company": { "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "description": "The address as it was written; it is unique in the workspace ignoring ASCII case.", "type": "string" }, "family_name": { "type": [ "string", "null" ] }, "fields": { "description": "The person's custom values, by field key.", "type": "object" }, "given_name": { "type": [ "string", "null" ] }, "group_ids": { "description": "The groups the person belongs to, at most 100.", "items": { "$ref": "#/components/schemas/Id_Group" }, "type": "array" }, "id": { "$ref": "#/components/schemas/Id_Person" }, "last_sent_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When mail was last sent to the person." }, { "type": "null" } ] }, "replied_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the person last replied." }, { "type": "null" } ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The person's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplacement of `group_ids` never erases a membership added since it was read.", "format": "int64", "type": "integer" } }, "required": [ "id", "email", "fields", "group_ids", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_QuotaScopeObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A quota scope as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_QuotaScope" }, "messages_per_day": { "description": "Messages a rolling day across its connections.", "format": "int32", "type": [ "integer", "null" ] }, "paused_detail": { "description": "What the provider said.", "type": [ "string", "null" ] }, "paused_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The provider paused the account until then." }, { "type": "null" } ] }, "provider": { "$ref": "#/components/schemas/Provider", "description": "The provider of the account; new values may be added." }, "recipients_per_day": { "description": "Recipients a rolling day across its connections.", "format": "int32", "type": [ "integer", "null" ] }, "scope_key": { "description": "The account: a project id, a tenant id, `account:region`, a relay host.", "type": "string" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The scope's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version. A pause\nthe provider imposes moves it too.", "format": "int64", "type": "integer" }, "webhook": { "oneOf": [ { "$ref": "#/components/schemas/WebhookObject", "description": "For SES: the webhook the account's configuration set posts to." }, { "type": "null" } ] }, "window_limit": { "description": "Units a short window allows (SES: its maximum send rate).", "format": "int32", "type": [ "integer", "null" ] }, "window_seconds": { "description": "The short window's length, in seconds.", "format": "int32", "type": [ "integer", "null" ] }, "window_unit": { "oneOf": [ { "$ref": "#/components/schemas/WindowUnit", "description": "What one submission is charged in the short window." }, { "type": "null" } ] } }, "required": [ "id", "provider", "scope_key", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_SegmentObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A segment as the API shows it.", "properties": { "computed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When `people_count` was counted; null in a list." }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "filter": { "$ref": "#/components/schemas/Filter", "description": "Who the segment means." }, "id": { "$ref": "#/components/schemas/Id_Segment" }, "name": { "type": "string" }, "people_count": { "description": "The people the filter matches, counted when the segment is retrieved, up to 10,000;\nnull in a list.", "format": "int64", "type": [ "integer", "null" ] }, "people_count_capped": { "description": "True when more than 10,000 people match; null in a list.", "type": [ "boolean", "null" ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The segment's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplaced filter never undoes a change made since it was read.", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "filter", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_SuppressionObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A suppression as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "description": "The address as it was suppressed; it matches its key ignoring ASCII case.", "type": "string" }, "evidence": { "description": "A summary of the evidence that created it; null for a manual suppression.", "type": [ "object", "null" ] }, "id": { "$ref": "#/components/schemas/Id_Suppression" }, "reason": { "$ref": "#/components/schemas/SuppressionReason", "description": "Why the address is suppressed. New values may be added." }, "source": { "$ref": "#/components/schemas/SuppressionSource", "description": "Who suppressed it: `manual`, `unsubscribe`, or the source of the evidence. New values may\nbe added." } }, "required": [ "id", "email", "reason", "source", "created_at" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "Page_ThreadObject": { "description": "One page of a list.", "properties": { "data": { "description": "At most `limit` rows, 100 at most.", "items": { "description": "A conversation.", "properties": { "campaign_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Campaign" }, { "type": "null" } ] }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Thread" }, "last_activity_at": { "$ref": "#/components/schemas/Timestamp" }, "last_message": { "oneOf": [ { "$ref": "#/components/schemas/ThreadMessage" }, { "type": "null" } ] }, "messages": { "oneOf": [ { "$ref": "#/components/schemas/ThreadMessages", "description": "On retrieve only: the latest messages." }, { "type": "null" } ] }, "participants": { "description": "The addresses taking part.", "items": { "type": "string" }, "type": "array" }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person" }, { "type": "null" } ] }, "sender_identity_id": { "$ref": "#/components/schemas/Id_SenderIdentity" }, "snoozed_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "Until when a `snoozed` thread sleeps." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ThreadStatus" }, "subject": { "type": [ "string", "null" ] }, "unread": { "description": "Something arrived that nobody marked read.", "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "status", "sender_identity_id", "connection_id", "participants", "unread", "last_activity_at", "created_at", "updated_at", "version" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "PersonObject": { "description": "A person as the API shows it.", "properties": { "company": { "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "description": "The address as it was written; it is unique in the workspace ignoring ASCII case.", "type": "string" }, "family_name": { "type": [ "string", "null" ] }, "fields": { "description": "The person's custom values, by field key.", "type": "object" }, "given_name": { "type": [ "string", "null" ] }, "group_ids": { "description": "The groups the person belongs to, at most 100.", "items": { "$ref": "#/components/schemas/Id_Group" }, "type": "array" }, "id": { "$ref": "#/components/schemas/Id_Person" }, "last_sent_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When mail was last sent to the person." }, { "type": "null" } ] }, "replied_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When the person last replied." }, { "type": "null" } ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The person's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplacement of `group_ids` never erases a membership added since it was read.", "format": "int64", "type": "integer" } }, "required": [ "id", "email", "fields", "group_ids", "created_at", "updated_at", "version" ], "type": "object" }, "PersonRef": { "description": "The person an enrollment is for.", "properties": { "email": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id_Person" }, "name": { "description": "The given and family names, when the person has either.", "type": [ "string", "null" ] } }, "required": [ "id", "email" ], "type": "object" }, "PreflightReason": { "description": "Why an address got its verdict; parsed back from the cache (`recipient_validations.reason`).", "enum": [ "mx", "implicit_mx", "syntax", "no_domain", "null_mx", "no_route", "dns_unavailable" ], "type": "string", "x-open-enum": true }, "PreflightResult": { "description": "What preflight found, in the order of the request's addresses.", "properties": { "data": { "description": "One per address asked about, at most 100.", "items": { "$ref": "#/components/schemas/Finding" }, "maxItems": 100, "type": "array" } }, "required": [ "data" ], "type": "object" }, "PreflightStatus": { "description": "The verdict on an address: what `POST /preflight` reports and, for a verdict DNS answered,\nwhat the preflight cache keeps (`recipient_validations.status`); `unknown` is never cached.", "enum": [ "routable", "invalid", "unknown" ], "type": "string", "x-open-enum": true }, "Problem": { "description": "A problem document as it is written on the wire, and as the OpenAPI document describes every\nerror answer of every operation (the schema `Problem`, served as `application/problem+json`).", "properties": { "code": { "$ref": "#/components/schemas/ProblemCode", "description": "The code from the closed registry; programs branch on it, never on the text. New codes\nmay be added." }, "detail": { "description": "What went wrong, for a person; never an internal cause.", "type": "string" }, "errors": { "description": "With `validation_failed` only: every invalid field.", "items": { "$ref": "#/components/schemas/FieldError" }, "type": "array" }, "instance": { "description": "The request's path.", "type": "string" }, "request_id": { "description": "The request's id, also in `X-Request-Id`: what support needs to find the request.", "type": "string" }, "retry_after": { "description": "With `429` and `503`: the seconds to wait, as in `Retry-After`.", "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "status": { "description": "The HTTP status.", "format": "int32", "minimum": 0, "type": "integer" }, "title": { "description": "Fixed per code.", "type": "string" }, "type": { "description": "`https://docs.norbelys.com/errors/`, a page that explains the code.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "instance", "request_id" ], "type": "object" }, "ProblemCode": { "description": "The closed registry of problem codes: programs branch on a problem's `code`, never on its\ntext. A code may be added, never repurposed.", "enum": [ "invalid_request", "unauthorized", "forbidden", "session_required", "not_found", "archived", "method_not_allowed", "conflict", "invalid_state", "idempotency_in_progress", "precondition_failed", "payload_too_large", "unsupported_media_type", "validation_failed", "idempotency_mismatch", "suppressed", "captcha_failed", "insufficient_scope", "rate_limited", "quota_exceeded", "internal_error", "service_unavailable", "timeout" ], "type": "string", "x-open-enum": true }, "Provider": { "description": "The provider behind a connection (`connections.provider`).", "enum": [ "smtp", "google", "microsoft", "ses", "sendgrid", "mailgun", "norbelys" ], "type": "string", "x-open-enum": true }, "QuotaScopeObject": { "description": "A quota scope as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_QuotaScope" }, "messages_per_day": { "description": "Messages a rolling day across its connections.", "format": "int32", "type": [ "integer", "null" ] }, "paused_detail": { "description": "What the provider said.", "type": [ "string", "null" ] }, "paused_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "The provider paused the account until then." }, { "type": "null" } ] }, "provider": { "$ref": "#/components/schemas/Provider", "description": "The provider of the account; new values may be added." }, "recipients_per_day": { "description": "Recipients a rolling day across its connections.", "format": "int32", "type": [ "integer", "null" ] }, "scope_key": { "description": "The account: a project id, a tenant id, `account:region`, a relay host.", "type": "string" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The scope's version, also the response's `ETag`: `updated_at` in microseconds since the\nUnix epoch. An update sent with it in `If-Match` applies only to this version. A pause\nthe provider imposes moves it too.", "format": "int64", "type": "integer" }, "webhook": { "oneOf": [ { "$ref": "#/components/schemas/WebhookObject", "description": "For SES: the webhook the account's configuration set posts to." }, { "type": "null" } ] }, "window_limit": { "description": "Units a short window allows (SES: its maximum send rate).", "format": "int32", "type": [ "integer", "null" ] }, "window_seconds": { "description": "The short window's length, in seconds.", "format": "int32", "type": [ "integer", "null" ] }, "window_unit": { "oneOf": [ { "$ref": "#/components/schemas/WindowUnit", "description": "What one submission is charged in the short window." }, { "type": "null" } ] } }, "required": [ "id", "provider", "scope_key", "created_at", "updated_at", "version" ], "type": "object" }, "Rates": { "description": "Ratios per 10,000 accepted messages; null means no denominator, never zero success.", "properties": { "bounced": { "description": "Permanent failures per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] }, "clicked": { "description": "Human unique clicks per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] }, "complained": { "description": "Complaints per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] }, "delivered": { "description": "Recipient-server acceptance per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] }, "opened": { "description": "Human unique opens per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] }, "replied": { "description": "Human replies per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] }, "unsubscribed": { "description": "Unsubscribes per 10,000 sends.", "format": "int64", "type": [ "integer", "null" ] } }, "type": "object" }, "ReceivingInput": { "additionalProperties": false, "description": "The folders to read.", "properties": { "folders": { "description": "Folder names at the provider, at most 10; `INBOX` is the inbox.", "items": { "type": "string" }, "type": "array" } }, "required": [ "folders" ], "type": "object" }, "ReceivingObject": { "description": "What a connection reads, as the API shows it.", "properties": { "folders": { "description": "The folders, oldest first; a disabled one is no longer read. Every enabled folder is shown,\nand disabled ones while there is room.", "items": { "$ref": "#/components/schemas/FolderObject" }, "maxItems": 10, "type": "array" } }, "required": [ "folders" ], "type": "object" }, "RecipientRef": { "description": "Why an event's recipient is known (`delivery_events.recipient_ref`).", "enum": [ "named", "single_envelope", "unknown" ], "type": "string", "x-open-enum": true }, "ReleaseHolds": { "additionalProperties": false, "description": "The body of `POST /messages/{id}/release_holds`.", "properties": { "evidence": { "description": "What shows the holds no longer apply, for the record: what the person checked. At most\n2,000 characters.", "type": "string" } }, "required": [ "evidence" ], "type": "object" }, "ReplayEndpoint": { "additionalProperties": false, "description": "The body of `POST /webhook_endpoints/{id}/replay`.", "properties": { "since": { "$ref": "#/components/schemas/Timestamp", "description": "Reopen the deliveries of events created at or after this instant. It must be within the\nreplay window (about six days back with daily partitions and a week online)." } }, "required": [ "since" ], "type": "object" }, "Resolution": { "description": "How a person settles an `uncertain` message.", "enum": [ "sent", "failed" ], "type": "string" }, "ResolveMessage": { "additionalProperties": false, "description": "The body of `POST /messages/{id}/resolve`.", "properties": { "evidence": { "description": "What shows it, for the record: where the message was found, or why it was not sent. At\nmost 2,000 characters.", "type": "string" }, "state": { "$ref": "#/components/schemas/Resolution", "description": "`sent` when the provider took the message, `failed` when it was not sent." } }, "required": [ "state", "evidence" ], "type": "object" }, "Review": { "additionalProperties": false, "description": "The body of `POST /inbound_messages/{id}/review`.", "properties": { "decision": { "$ref": "#/components/schemas/Decision" } }, "required": [ "decision" ], "type": "object" }, "ReviewDecision": { "description": "A person's decision on what an inbound message proposed.", "enum": [ "confirmed", "dismissed" ], "type": "string", "x-open-enum": true }, "ReviewProposal": { "description": "What confirming a review applies (`inbound_messages.review_proposal`).", "oneOf": [ { "description": "Suppress `email` for `reason`.", "properties": { "action": { "enum": [ "suppress" ], "type": "string", "x-open-enum": true }, "email": { "type": "string" }, "reason": { "$ref": "#/components/schemas/SuppressionReason" } }, "required": [ "email", "reason", "action" ], "type": "object" }, { "description": "Move the person at `email` to `new_email`; without a new address, the old one is\nsuppressed as `address_changed`.", "properties": { "action": { "enum": [ "change_address" ], "type": "string", "x-open-enum": true }, "email": { "type": "string" }, "new_email": { "type": [ "string", "null" ] } }, "required": [ "email", "action" ], "type": "object" }, { "description": "Apply an AI verdict that was not confident enough to apply by itself, or that was sampled\nfor a person to check: `classification` and `sentiment` as the message stores them, and the\nmodel's confidence in percent. Confirming applies it; either decision is the label that\nmeasures the classifier's precision and recall on real mail.", "properties": { "action": { "enum": [ "classify" ], "type": "string", "x-open-enum": true }, "classification": { "$ref": "#/components/schemas/InboundClassification" }, "confidence_percent": { "format": "int32", "minimum": 0, "type": "integer" }, "sentiment": { "$ref": "#/components/schemas/Sentiment" } }, "required": [ "classification", "sentiment", "confidence_percent", "action" ], "type": "object" } ] }, "RowProblem": { "description": "One problem of an import's row.", "properties": { "field": { "description": "The column or attribute at fault (`email`, `fields.industry`, …).", "type": "string" }, "problem": { "type": "string" }, "row": { "description": "The row: in a CSV file, its position as a spreadsheet numbers it (the header is row 1);\nin a JSON import, the person's position in `people` (from 1).", "format": "int64", "type": "integer" } }, "required": [ "row", "field", "problem" ], "type": "object" }, "ScheduleInput": { "additionalProperties": false, "description": "A campaign's schedule in a create or an update; a field left out keeps its value.", "properties": { "send_window": { "oneOf": [ { "$ref": "#/components/schemas/SendWindow", "description": "The days (1 Monday to 7 Sunday) and hours (`HH:MM`, on 5-minute marks) campaign mail may\nbe sent; `null` removes it." }, { "type": "null" } ] }, "start_at": { "description": "No step runs before this instant; `null` removes it.", "type": [ "string", "null" ] }, "timezone": { "description": "An IANA time zone, such as `Europe/Madrid` (default `UTC`).", "type": [ "string", "null" ] } }, "type": "object" }, "ScheduleObject": { "description": "When the campaign sends.", "properties": { "send_window": { "oneOf": [ { "$ref": "#/components/schemas/SendWindow", "description": "The days and hours campaign mail may be sent; `null`: any time." }, { "type": "null" } ] }, "start_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "No step runs before this instant." }, { "type": "null" } ] }, "timezone": { "description": "The IANA time zone of the send window.", "type": "string" } }, "required": [ "timezone" ], "type": "object" }, "SegmentObject": { "description": "A segment as the API shows it.", "properties": { "computed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When `people_count` was counted; null in a list." }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "filter": { "$ref": "#/components/schemas/Filter", "description": "Who the segment means." }, "id": { "$ref": "#/components/schemas/Id_Segment" }, "name": { "type": "string" }, "people_count": { "description": "The people the filter matches, counted when the segment is retrieved, up to 10,000;\nnull in a list.", "format": "int64", "type": [ "integer", "null" ] }, "people_count_capped": { "description": "True when more than 10,000 people match; null in a list.", "type": [ "boolean", "null" ] }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "The segment's version, also the response's `ETag`: `updated_at` in microseconds since\nthe Unix epoch. An update sent with it in `If-Match` applies only to this version, so a\nreplaced filter never undoes a change made since it was read.", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "filter", "created_at", "updated_at", "version" ], "type": "object" }, "SendWindow": { "description": "The days and hours a connection may submit campaign mail, in its time zone: the days of the\nweek (1 is Monday, 7 is Sunday) and an opening and a closing time on 5-minute marks, the\nopening first (a window never crosses midnight).", "properties": { "days": { "description": "The days of the week, 1 (Monday) to 7 (Sunday), each once, in order.", "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" }, "end": { "description": "The closing time, `HH:MM`, after the opening; `24:00` closes at midnight.", "type": "string" }, "start": { "description": "The opening time, `HH:MM`.", "type": "string" } }, "required": [ "days", "start", "end" ], "type": "object" }, "SendersInput": { "additionalProperties": false, "description": "A campaign's pool in a create or an update; a field left out keeps its value.", "properties": { "identity_ids": { "description": "The identities the campaign names (`sid_…`), at most 500; replaces the list.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "on_sender_removed": { "oneOf": [ { "$ref": "#/components/schemas/OnSenderRemoved", "description": "`reassign` (default) or `stop`." }, { "type": "null" } ] }, "tags": { "description": "Tags whose enabled identities join the pool, at most 20, each 1 to 50 characters.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "SendersObject": { "description": "The campaign's pool of senders.", "properties": { "identity_ids": { "description": "The identities the campaign names (`sid_…`).", "items": { "$ref": "#/components/schemas/Id_SenderIdentity" }, "type": "array" }, "on_sender_removed": { "$ref": "#/components/schemas/OnSenderRemoved", "description": "What happens to a conversation whose sender leaves the pool: `reassign` (another sender\nof the pool takes the next step, in a new thread) or `stop`." }, "tags": { "description": "Every enabled identity carrying one of these tags joins the pool, as it is when a sender\nis assigned.", "items": { "type": "string" }, "type": "array" } }, "required": [ "identity_ids", "tags", "on_sender_removed" ], "type": "object" }, "SendingDomainStatus": { "description": "A sending domain's lifecycle (`sending_domains.status`): `pending_verification` until its\nownership record is found (`verifying` while a check runs), then `verified`; with tracking,\n`pending_certificate` until its tracking host serves, then `active`; `suspended` when its\nproven ownership record is gone; `deleting` while it is removed.", "enum": [ "pending_verification", "verifying", "verified", "pending_certificate", "active", "suspended", "deleting" ], "type": "string", "x-open-enum": true }, "Sentiment": { "description": "The writer's attitude towards the outreach (`inbound_messages.sentiment`), as AI judges it or\na person corrects it.", "enum": [ "positive", "neutral", "negative" ], "type": "string", "x-open-enum": true }, "SkipReason": { "description": "Why a person was not enrolled.", "enum": [ "not_found", "suppressed", "already_enrolled" ], "type": "string", "x-open-enum": true }, "Skipped": { "description": "A person an enrollment skipped.", "properties": { "email": { "description": "The address, when the request named the person by it.", "type": [ "string", "null" ] }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person", "description": "The person, when known." }, { "type": "null" } ] }, "reason": { "$ref": "#/components/schemas/SkipReason", "description": "`not_found`, `suppressed` or `already_enrolled`." } }, "required": [ "reason" ], "type": "object" }, "SmtpAuthorization": { "description": "The private transport login selected after checking a live workspace API key.", "properties": { "username": { "type": "string" } }, "required": [ "username" ], "type": "object" }, "SmtpInput": { "additionalProperties": false, "description": "An SMTP endpoint and its login, as a request gives it.", "properties": { "configuration_set": { "description": "Amazon SES: the configuration set every message names.", "type": [ "string", "null" ] }, "host": { "description": "The host name.", "type": "string" }, "password": { "description": "The password, app password or relay key.", "type": "string" }, "port": { "description": "The port.", "format": "int32", "minimum": 0, "type": "integer" }, "security": { "$ref": "#/components/schemas/SmtpSecurity", "description": "`tls` (465), `starttls` (587), or `plain` (a private host in development only)." }, "username": { "description": "The login; an SMTP login's is its account (`account_email`).", "type": [ "string", "null" ] } }, "required": [ "host", "port", "security", "password" ], "type": "object" }, "SmtpPatch": { "additionalProperties": false, "description": "A change of an SMTP endpoint: the fields given replace the stored ones.", "properties": { "configuration_set": { "type": [ "string", "null" ] }, "host": { "type": [ "string", "null" ] }, "password": { "description": "A new password: the connection is verified again.", "type": [ "string", "null" ] }, "port": { "format": "int32", "minimum": 0, "type": [ "integer", "null" ] }, "security": { "oneOf": [ { "$ref": "#/components/schemas/SmtpSecurity" }, { "type": "null" } ] }, "username": { "type": [ "string", "null" ] } }, "type": "object" }, "SmtpSecurity": { "description": "How an SMTP session is secured.", "enum": [ "tls", "starttls", "plain" ], "type": "string", "x-open-enum": true }, "SmtpSettings": { "description": "An SMTP endpoint, as stored in `connections.smtp` and shown; never the password.", "properties": { "configuration_set": { "description": "The Amazon SES configuration set every message names, so SES publishes its events.", "type": [ "string", "null" ] }, "host": { "description": "The host name.", "type": "string" }, "port": { "description": "The port.", "format": "int32", "minimum": 0, "type": "integer" }, "security": { "$ref": "#/components/schemas/SmtpSecurity", "description": "How the session is secured." }, "username": { "description": "The login.", "type": "string" } }, "required": [ "host", "port", "security", "username" ], "type": "object" }, "SnippetsFallback": { "description": "Why the template's defaults are used (`messages.snippets_fallback`; a message shows it as\n`snippets_fallback`).", "enum": [ "off", "unavailable", "unusable", "over_budget", "paused", "deadline", "refused", "truncated", "invalid", "provider" ], "type": "string", "x-open-enum": true }, "StatsObject": { "description": "The campaign's counters, from the analytics rollup.", "properties": { "bounced": { "format": "int64", "type": "integer" }, "clicked": { "format": "int64", "type": "integer" }, "computed_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "How far the rollup had counted when these were read; `null` before its first run." }, { "type": "null" } ] }, "opened": { "format": "int64", "type": "integer" }, "replied": { "format": "int64", "type": "integer" }, "sent": { "format": "int64", "type": "integer" }, "unsubscribed": { "format": "int64", "type": "integer" } }, "required": [ "sent", "opened", "clicked", "replied", "bounced", "unsubscribed" ], "type": "object" }, "StepEnrollments": { "description": "The live enrollments at one step of a campaign.", "properties": { "live": { "description": "Live enrollments (`active` or `paused`) at this step now.", "format": "int64", "type": "integer" }, "step_id": { "$ref": "#/components/schemas/Id_Step" } }, "required": [ "step_id", "live" ], "type": "object" }, "StepFailure": { "description": "Why one person's message was refused, as the problem a single request would have answered.", "properties": { "code": { "$ref": "#/components/schemas/ProblemCode", "description": "The problem's code: `not_found`, `suppressed`, `validation_failed` or `invalid_state`." }, "detail": { "type": "string" }, "errors": { "items": { "$ref": "#/components/schemas/FieldError" }, "type": "array" } }, "required": [ "code", "detail", "errors" ], "type": "object" }, "StepInput": { "additionalProperties": false, "description": "A step in a create or an update (see the module for the merge rules).", "properties": { "allocation": { "oneOf": [ { "$ref": "#/components/schemas/Allocation", "description": "`balanced` (default), `weighted` or `automatic`." }, { "type": "null" } ] }, "delay_seconds": { "description": "0 to 31,536,000 seconds after the previous step's message was sent (default 0).", "format": "int32", "type": [ "integer", "null" ] }, "id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Step", "description": "The step to keep or change (`stp_…`); absent for a new step." }, { "type": "null" } ] }, "name": { "description": "1 to 200 characters; required for a new step.", "type": [ "string", "null" ] }, "personalisation_prompt": { "description": "What the AI writes each message's snippets from, 1 to 4,000 characters; `null` removes\nit.", "type": [ "string", "null" ] }, "same_thread": { "description": "Continue the conversation's thread (default `true`).", "type": [ "boolean", "null" ] }, "variants": { "description": "1 to 50 variants; required for a new step.", "items": { "$ref": "#/components/schemas/VariantInput" }, "type": [ "array", "null" ] }, "winner_rule": { "oneOf": [ { "$ref": "#/components/schemas/WinnerRuleInput", "description": "The rule of an `automatic` test (default: replies, a week, 100 messages per variant)." }, { "type": "null" } ] }, "winner_variant_id": { "description": "The variant the step now sends to everyone (`var_…`), one of its variants; `null` clears\nit.", "type": [ "string", "null" ] } }, "type": "object" }, "StepObject": { "description": "A step of a campaign as the API shows it, with its current revision.", "properties": { "allocation": { "$ref": "#/components/schemas/Allocation" }, "delay_seconds": { "description": "How long after the previous step's message was sent this step is due; the first step\nruns when a person is enrolled, so its delay is not used.", "format": "int32", "type": "integer" }, "id": { "$ref": "#/components/schemas/Id_Step" }, "name": { "type": "string" }, "personalisation_prompt": { "description": "What the AI writes each message's snippets from (the `variables` namespace); `null`: the\ntemplates alone.", "type": [ "string", "null" ] }, "position": { "description": "1 for the first step.", "format": "int32", "type": "integer" }, "revision": { "description": "The current revision: what messages created now are made from.", "format": "int32", "type": "integer" }, "same_thread": { "description": "Whether the step's message continues the conversation's thread (a reply to the previous\nmessage) or starts a new one.", "type": "boolean" }, "variants": { "description": "The variants this revision offers.", "items": { "$ref": "#/components/schemas/VariantObject" }, "maxItems": 50, "type": "array" }, "winner": { "oneOf": [ { "$ref": "#/components/schemas/WinnerObject", "description": "The variant this revision now sends to everyone, once chosen." }, { "type": "null" } ] }, "winner_rule": { "$ref": "#/components/schemas/WinnerRuleObject" } }, "required": [ "id", "position", "name", "revision", "delay_seconds", "same_thread", "allocation", "winner_rule", "variants" ], "type": "object" }, "StepResult": { "description": "One person's result: the message queued, or why there is none.", "properties": { "error": { "oneOf": [ { "$ref": "#/components/schemas/StepFailure" }, { "type": "null" } ] }, "message": { "oneOf": [ { "$ref": "#/components/schemas/MessageObject" }, { "type": "null" } ] }, "person_id": { "type": "string" } }, "required": [ "person_id" ], "type": "object" }, "StepResults": { "description": "The results of the step-content form for several people, in the order they were given.", "properties": { "data": { "description": "One per person given, at most 100.", "items": { "$ref": "#/components/schemas/StepResult" }, "maxItems": 100, "type": "array" } }, "required": [ "data" ], "type": "object" }, "StopOnReply": { "description": "Which enrollments a person's reply stops (`campaigns.stop_on_reply`).", "enum": [ "all", "campaign", "none" ], "type": "string", "x-open-enum": true }, "StopRulesInput": { "additionalProperties": false, "description": "A campaign's stop rules in a create or an update; a field left out keeps its value.", "properties": { "company_on_reply": { "type": [ "boolean", "null" ] }, "cooldown_hours": { "description": "0 to 8,760 hours (default 72).", "format": "int32", "type": [ "integer", "null" ] }, "on_reply": { "oneOf": [ { "$ref": "#/components/schemas/StopOnReply", "description": "`all` (default), `campaign` or `none`." }, { "type": "null" } ] } }, "type": "object" }, "StopRulesObject": { "description": "When an enrollment stops before its last step.", "properties": { "company_on_reply": { "description": "Whether a reply also stops this campaign's enrollments of people at the same email\ndomain (the same company).", "type": "boolean" }, "cooldown_hours": { "description": "A new enrollment's first step waits until this many hours have passed since the person's\nlast campaign message from the workspace.", "format": "int32", "type": "integer" }, "on_reply": { "$ref": "#/components/schemas/StopOnReply", "description": "Whose enrollments a person's reply stops: `all` (the person's live enrollments in every\ncampaign), `campaign` (this one only) or `none`." } }, "required": [ "on_reply", "company_on_reply", "cooldown_hours" ], "type": "object" }, "SubmissionPhase": { "description": "The protocol step a submission ended in (`attempts.phase`, `delivery_events.phase`).", "enum": [ "connect", "auth", "mail_from", "rcpt_to", "data", "api" ], "type": "string", "x-open-enum": true }, "SuppressedAddresses": { "description": "What a list of addresses did (the list form of `POST /suppressions`).", "properties": { "already": { "description": "Addresses that were suppressed before this request, for any reason; they stay as they\nwere.", "minimum": 0, "type": "integer" }, "created": { "description": "Addresses this request suppressed.", "minimum": 0, "type": "integer" }, "invalid": { "description": "The entries that are not addresses, in the order given; nothing was done for them.", "items": { "$ref": "#/components/schemas/InvalidAddress" }, "maxItems": 1000, "type": "array" } }, "required": [ "created", "already", "invalid" ], "type": "object" }, "SuppressionForm": { "description": "The forms of `POST /suppressions`: one address or a list. Each form refuses the member the\nother requires (`email`, `emails`), so a body is one form only.", "oneOf": [ { "$ref": "#/components/schemas/CreateSuppression" }, { "$ref": "#/components/schemas/CreateSuppressions" } ] }, "SuppressionObject": { "description": "A suppression as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "description": "The address as it was suppressed; it matches its key ignoring ASCII case.", "type": "string" }, "evidence": { "description": "A summary of the evidence that created it; null for a manual suppression.", "type": [ "object", "null" ] }, "id": { "$ref": "#/components/schemas/Id_Suppression" }, "reason": { "$ref": "#/components/schemas/SuppressionReason", "description": "Why the address is suppressed. New values may be added." }, "source": { "$ref": "#/components/schemas/SuppressionSource", "description": "Who suppressed it: `manual`, `unsubscribe`, or the source of the evidence. New values may\nbe added." } }, "required": [ "id", "email", "reason", "source", "created_at" ], "type": "object" }, "SuppressionReason": { "description": "Why an address is suppressed.", "enum": [ "unsubscribe", "bounce", "complaint", "manual", "address_changed", "account_closed", "no_mail_service" ], "type": "string", "x-open-enum": true }, "SuppressionSource": { "description": "Who or what created a suppression: a person, the recipient's unsubscribe, or the source of\nthe delivery event that proved it.", "enum": [ "manual", "unsubscribe", "smtp", "provider_api", "provider_webhook", "dsn", "arf", "inbound_notice" ], "type": "string", "x-open-enum": true }, "SuppressionSummary": { "description": "A suppression, as preflight shows it.", "properties": { "id": { "$ref": "#/components/schemas/Id_Suppression" }, "reason": { "$ref": "#/components/schemas/SuppressionReason", "description": "Why the address is suppressed. New values may be added." } }, "required": [ "id", "reason" ], "type": "object" }, "ThreadMessage": { "description": "One message of a thread, outbound or inbound.", "properties": { "at": { "$ref": "#/components/schemas/Timestamp", "description": "When it was sent (or created, while it waits) or received." }, "classification": { "oneOf": [ { "$ref": "#/components/schemas/InboundClassification", "description": "An inbound message's classification." }, { "type": "null" } ] }, "direction": { "$ref": "#/components/schemas/Direction" }, "from": { "type": [ "string", "null" ] }, "id": { "description": "A message id (`msg_…`) for outbound mail, an inbound message id (`inb_…`) for inbound.", "type": "string" }, "state": { "oneOf": [ { "$ref": "#/components/schemas/MessageState", "description": "An outbound message's state; null for inbound mail." }, { "type": "null" } ] }, "subject": { "type": [ "string", "null" ] }, "text": { "description": "The start of its text, when it has one of its own.", "type": [ "string", "null" ] }, "to": { "description": "The addresses an outbound message went to; empty for inbound mail.", "items": { "type": "string" }, "type": "array" } }, "required": [ "direction", "id", "to", "at" ], "type": "object" }, "ThreadMessages": { "description": "A thread's latest messages.", "properties": { "data": { "description": "Oldest first.", "items": { "$ref": "#/components/schemas/ThreadMessage" }, "maxItems": 50, "type": "array" }, "has_more": { "description": "Older messages exist.", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "ThreadObject": { "description": "A conversation.", "properties": { "campaign_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Campaign" }, { "type": "null" } ] }, "connection_id": { "$ref": "#/components/schemas/Id_Connection" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/Id_Thread" }, "last_activity_at": { "$ref": "#/components/schemas/Timestamp" }, "last_message": { "oneOf": [ { "$ref": "#/components/schemas/ThreadMessage" }, { "type": "null" } ] }, "messages": { "oneOf": [ { "$ref": "#/components/schemas/ThreadMessages", "description": "On retrieve only: the latest messages." }, { "type": "null" } ] }, "participants": { "description": "The addresses taking part.", "items": { "type": "string" }, "type": "array" }, "person_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Person" }, { "type": "null" } ] }, "sender_identity_id": { "$ref": "#/components/schemas/Id_SenderIdentity" }, "snoozed_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "Until when a `snoozed` thread sleeps." }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/ThreadStatus" }, "subject": { "type": [ "string", "null" ] }, "unread": { "description": "Something arrived that nobody marked read.", "type": "boolean" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "id", "status", "sender_identity_id", "connection_id", "participants", "unread", "last_activity_at", "created_at", "updated_at", "version" ], "type": "object" }, "ThreadStatus": { "description": "A thread's status as shown: `snoozed` turns `open` once its time passes.", "enum": [ "open", "snoozed", "archived" ], "type": "string", "x-open-enum": true }, "Timestamp": { "format": "date-time", "type": "string" }, "Tracking": { "description": "What a message tracks, frozen when it was created.", "properties": { "clicks": { "description": "Its links lead through click links.", "type": "boolean" }, "hostname": { "description": "The campaign's own tracking host, when it has one; the platform's otherwise.", "type": [ "string", "null" ] }, "opens": { "description": "An open pixel is added to its HTML.", "type": "boolean" } }, "required": [ "opens", "clicks" ], "type": "object" }, "TrackingDomainObject": { "description": "A mail domain's separately configured tracking hostname.", "properties": { "checked_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "id": { "$ref": "#/components/schemas/Id_SendingDomain" }, "records": { "items": { "$ref": "#/components/schemas/DnsRecord" }, "maxItems": 2, "type": "array" }, "status": { "type": "string" }, "verified_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] } }, "required": [ "id", "hostname", "status", "records" ], "type": "object" }, "TrackingInput": { "additionalProperties": false, "description": "A campaign's tracking in a create or an update; a field left out keeps its value.", "properties": { "clicks": { "type": [ "boolean", "null" ] }, "domain_id": { "description": "A sending domain whose tracking host the links use (`dom_…`); `null`: the platform's.", "type": [ "string", "null" ] }, "opens": { "type": [ "boolean", "null" ] } }, "type": "object" }, "TrackingObject": { "description": "What the campaign's messages track.", "properties": { "clicks": { "type": "boolean" }, "domain_id": { "oneOf": [ { "$ref": "#/components/schemas/Id_SendingDomain", "description": "The sending domain whose tracking host the links use (`dom_…`); `null`: the platform's." }, { "type": "null" } ] }, "opens": { "type": "boolean" } }, "required": [ "opens", "clicks" ], "type": "object" }, "Transport": { "description": "The transport a connection submits over (`connections.transport`).", "enum": [ "smtp", "api" ], "type": "string", "x-open-enum": true }, "UpdateCampaign": { "additionalProperties": false, "description": "The body of `PATCH /campaigns/{id}`: every member optional; `steps` replaces the ordered list.", "properties": { "name": { "type": [ "string", "null" ] }, "schedule": { "oneOf": [ { "$ref": "#/components/schemas/ScheduleInput" }, { "type": "null" } ] }, "senders": { "oneOf": [ { "$ref": "#/components/schemas/SendersInput" }, { "type": "null" } ] }, "steps": { "description": "The whole ordered list, at most 50: a step by `id` alone stays unchanged, by `id` with\nfields takes them, without `id` is new, and one left out is removed (refused once it has\nsent). Together the campaign's steps then, kept ones included, hold at most 1.5 MiB of\nnames, prompts and templates.", "items": { "$ref": "#/components/schemas/StepInput" }, "type": [ "array", "null" ] }, "stop_rules": { "oneOf": [ { "$ref": "#/components/schemas/StopRulesInput" }, { "type": "null" } ] }, "tracking": { "oneOf": [ { "$ref": "#/components/schemas/TrackingInput" }, { "type": "null" } ] } }, "type": "object" }, "UpdateConnection": { "additionalProperties": false, "description": "The body of `PATCH /connections/{id}`: every field is optional; `null` clears a nullable one.", "properties": { "api_credential": { "oneOf": [ { "$ref": "#/components/schemas/ApiCredentialInput", "description": "A relay's API credential (SES, SendGrid, Mailgun), or `null` to remove it: the\nconnection is verified again." }, { "type": "null" } ] }, "daily_limit": { "format": "int32", "type": [ "integer", "null" ] }, "identities": { "description": "The whole list of identities: one with its `id` is replaced, one without is added, one\nleft out is removed (one with history is kept: disable it instead).", "items": { "$ref": "#/components/schemas/IdentityInput" }, "maxItems": 1000, "type": [ "array", "null" ] }, "imap": { "oneOf": [ { "$ref": "#/components/schemas/ImapInput", "description": "New IMAP settings, or `null` to stop reading over IMAP: verified again." }, { "type": "null" } ] }, "paused": { "description": "Pause or resume sending.", "type": [ "boolean", "null" ] }, "quota_scope_id": { "description": "Another quota scope, or `null` (not for SES).", "type": [ "string", "null" ] }, "receiving": { "oneOf": [ { "$ref": "#/components/schemas/ReceivingInput", "description": "The whole list of folders to read." }, { "type": "null" } ] }, "send_interval_minutes": { "description": "Minutes between campaign emails. Norbelys accepts exact whole minutes, 1 to 1,440,\nincluding activation on an unpaced connection. Existing paced mailboxes and SES\nround up to whole 5-minute slots.", "format": "int32", "type": [ "integer", "null" ] }, "send_window": { "oneOf": [ { "$ref": "#/components/schemas/SendWindow" }, { "type": "null" } ] }, "smtp": { "oneOf": [ { "$ref": "#/components/schemas/SmtpPatch", "description": "New SMTP settings or credential: the connection is verified again." }, { "type": "null" } ] }, "timezone": { "type": [ "string", "null" ] }, "warmup_stage": { "format": "int32", "type": [ "integer", "null" ] }, "webhook": { "oneOf": [ { "$ref": "#/components/schemas/WebhookInput", "description": "A relay's webhook verification material." }, { "type": "null" } ] } }, "type": "object" }, "UpdateDomain": { "additionalProperties": false, "description": "The body of `PATCH /sending_domains/{id}`.", "properties": { "purpose": { "oneOf": [ { "$ref": "#/components/schemas/DomainPurpose", "description": "Change this hostname's use. Disabling mail directions stops those operations while retaining mailbox history." }, { "type": "null" } ] }, "tracking_enabled": { "description": "Serve tracking links from it; `verify` then checks its CNAME.", "type": [ "boolean", "null" ] }, "tracking_hostname": { "description": "Set a separate tracking hostname; null detaches it without deleting its records or history.", "type": [ "string", "null" ] } }, "type": "object" }, "UpdateEndpoint": { "additionalProperties": false, "description": "The body of `PATCH /webhook_endpoints/{id}`.", "properties": { "enabled": { "description": "`false` disables the endpoint (its pending deliveries stop); `true` enables it again.", "type": [ "boolean", "null" ] }, "event_types": { "description": "The new list of event types, 1 to 32, replacing the old one.", "items": { "$ref": "#/components/schemas/EventType" }, "type": [ "array", "null" ] }, "filters": { "oneOf": [ { "$ref": "#/components/schemas/Filters", "description": "Resource filters; an empty object accepts every resource." }, { "type": "null" } ] }, "headers": { "additionalProperties": { "type": "string" }, "description": "Custom headers, replaced together, sealed at rest and never returned.", "propertyNames": { "type": "string" }, "type": [ "object", "null" ] }, "url": { "description": "A new URL.", "type": [ "string", "null" ] } }, "type": "object" }, "UpdateField": { "additionalProperties": false, "description": "The body of `PATCH /fields/{id}`.", "properties": { "label": { "description": "A new label, 1 to 100 characters.", "type": [ "string", "null" ] }, "options": { "description": "An enum's options, replacing the current ones whole. An option a person holds, or a\nsegment compares with, cannot be removed.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdateGroup": { "additionalProperties": false, "description": "The body of `PATCH /groups/{id}`.", "properties": { "description": { "description": "A new description; `null` clears it.", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "UpdateInbound": { "additionalProperties": false, "description": "The body of `PATCH /inbound_messages/{id}`.", "properties": { "classification": { "oneOf": [ { "$ref": "#/components/schemas/InboundClassification", "description": "The corrected classification." }, { "type": "null" } ] }, "sentiment": { "oneOf": [ { "$ref": "#/components/schemas/Sentiment", "description": "The corrected sentiment; `null` clears it." }, { "type": "null" } ] } }, "type": "object" }, "UpdatePerson": { "additionalProperties": false, "description": "The body of `PATCH /people/{id}`: absent members stay as they are.", "properties": { "company": { "type": [ "string", "null" ] }, "email": { "description": "A new address; unique in the workspace ignoring ASCII case.", "format": "email", "type": [ "string", "null" ] }, "family_name": { "type": [ "string", "null" ] }, "fields": { "description": "Custom values merged into the person's; `null` removes one.", "type": [ "object", "null" ] }, "given_name": { "description": "A new given name; `null` clears it.", "type": [ "string", "null" ] }, "group_ids": { "description": "The person's groups, replacing the current ones whole; at most 100.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdateQuotaScope": { "additionalProperties": false, "description": "The body of `PATCH /quota_scopes/{id}`: a limit given replaces the stored one, `null` clears\nit, an absent one stays; the short window's three fields change together.", "properties": { "messages_per_day": { "format": "int32", "type": [ "integer", "null" ] }, "recipients_per_day": { "format": "int32", "type": [ "integer", "null" ] }, "window_limit": { "format": "int32", "type": [ "integer", "null" ] }, "window_seconds": { "format": "int32", "type": [ "integer", "null" ] }, "window_unit": { "oneOf": [ { "$ref": "#/components/schemas/WindowUnit" }, { "type": "null" } ] } }, "type": "object" }, "UpdateSegment": { "additionalProperties": false, "description": "The body of `PATCH /segments/{id}`.", "properties": { "filter": { "oneOf": [ { "$ref": "#/components/schemas/Filter", "description": "A new filter, replacing the current one." }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "UpdateThread": { "additionalProperties": false, "description": "The body of `PATCH /threads/{id}`.", "properties": { "snoozed_until": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "Until when a snoozed thread sleeps: required with `snoozed`, refused otherwise." }, { "type": "null" } ] }, "status": { "oneOf": [ { "$ref": "#/components/schemas/ThreadStatus", "description": "`open`, `snoozed` (with `snoozed_until`) or `archived`." }, { "type": "null" } ] }, "unread": { "description": "`false` marks it read.", "type": [ "boolean", "null" ] } }, "type": "object" }, "Upload": { "additionalProperties": false, "properties": { "content_base64": { "description": "Standard base64 of at most 512 KiB of decoded data.", "type": "string" }, "content_type": { "description": "Media type, for example application/pdf.", "type": "string" }, "filename": { "description": "A filename without path separators or control characters, at most 255 bytes.", "type": "string" } }, "required": [ "filename", "content_type", "content_base64" ], "type": "object" }, "Usage": { "description": "The daily budget's use today and yesterday (UTC days).", "properties": { "today": { "$ref": "#/components/schemas/UsageDay" }, "yesterday": { "$ref": "#/components/schemas/UsageDay" } }, "required": [ "today", "yesterday" ], "type": "object" }, "UsageDay": { "description": "A day's use of the daily budget.", "properties": { "reserved": { "description": "Submissions claimed and not settled yet.", "format": "int32", "type": "integer" }, "used": { "description": "Submissions the provider accepted (or may have).", "format": "int32", "type": "integer" } }, "required": [ "used", "reserved" ], "type": "object" }, "VariantInput": { "additionalProperties": false, "description": "A variant in a create or an update (see the module for the merge rules).", "properties": { "bcc": { "description": "Blind-copied on every message of the variant, at most 20.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "cc": { "description": "Copied on every message of the variant, at most 20.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "html": { "description": "The HTML body template, at most 256 KiB; required for a new variant.", "type": [ "string", "null" ] }, "id": { "oneOf": [ { "$ref": "#/components/schemas/Id_Variant", "description": "The variant to keep or change (`var_…`); absent for a new variant." }, { "type": "null" } ] }, "name": { "description": "1 to 200 characters (default: a letter by position).", "type": [ "string", "null" ] }, "preheader": { "description": "The hidden preview text template, at most 1,000 characters; `null` removes it.", "type": [ "string", "null" ] }, "subject": { "description": "The subject template, 1 to 1,000 characters; required for a new variant.", "type": [ "string", "null" ] }, "weight": { "description": "The share under `weighted` allocation, 1 to 100 (default: the current weight, else 1).", "format": "int32", "type": [ "integer", "null" ] } }, "type": "object" }, "VariantObject": { "description": "A variant as its step offers it.", "properties": { "bcc": { "items": { "type": "string" }, "type": "array" }, "cc": { "items": { "type": "string" }, "type": "array" }, "html": { "description": "The HTML body template: shown on a campaign retrieved alone, absent from a list (bodies\ncan be large, and a list shows many variants).", "type": "string" }, "id": { "$ref": "#/components/schemas/Id_Variant" }, "name": { "type": "string" }, "preheader": { "description": "The hidden preview text template.", "type": [ "string", "null" ] }, "subject": { "description": "The subject template.", "type": "string" }, "version": { "description": "The version of its content the step's revision offers.", "format": "int32", "type": "integer" }, "weight": { "description": "Its share under `weighted` allocation, 1 to 100.", "format": "int32", "type": "integer" } }, "required": [ "id", "name", "version", "weight", "subject", "cc", "bcc" ], "type": "object" }, "WebhookDeliveryState": { "description": "Where a webhook delivery is (`webhook_deliveries.state`): `pending` while an attempt is due\nat `next_attempt_at`, `delivered`, `failed` once the schedule is exhausted, or `disabled`\nwhen its endpoint was disabled.", "enum": [ "pending", "delivered", "failed", "disabled" ], "type": "string", "x-open-enum": true }, "WebhookInput": { "additionalProperties": false, "description": "A relay's webhook verification material.", "properties": { "key": { "description": "Mailgun: the HTTP webhook signing key. SendGrid: the verification key its webhook shows\n(base64). SES: the ARN of the SNS topic the configuration set posts to.", "type": "string" } }, "required": [ "key" ], "type": "object" }, "WebhookObject": { "description": "A relay's provider webhook: where its callbacks are posted.", "properties": { "id": { "$ref": "#/components/schemas/Id_ProviderWebhook" }, "key_set": { "description": "Whether its verification material is set: SendGrid's verification key, Mailgun's\nsigning key, the SNS topic for SES; callbacks are refused until it is.", "type": "boolean" }, "url": { "description": "The URL to configure at the provider (an SES connection's quota scope names the one its\naccount subscribes).", "type": "string" } }, "required": [ "id", "url", "key_set" ], "type": "object" }, "WindowUnit": { "description": "What one submission is charged in a short window (`quota_scopes.window_unit`): one request,\nits recipients, or the provider's own units.", "enum": [ "requests", "recipients", "units" ], "type": "string", "x-open-enum": true }, "WinnerObject": { "description": "A revision's winner.", "properties": { "selected_at": { "$ref": "#/components/schemas/Timestamp" }, "selected_by": { "description": "`automatic`, or the user who chose it (`usr_…`).", "type": "string" }, "variant_id": { "$ref": "#/components/schemas/Id_Variant" } }, "required": [ "variant_id", "selected_at", "selected_by" ], "type": "object" }, "WinnerRuleInput": { "additionalProperties": false, "description": "A winner rule in a create or an update; a field left out keeps its value.", "properties": { "minimum_sample": { "description": "1 to 1,000,000 messages per variant.", "format": "int32", "type": [ "integer", "null" ] }, "objective": { "oneOf": [ { "$ref": "#/components/schemas/Objective" }, { "type": "null" } ] }, "observation_window_seconds": { "description": "1 to 31,536,000 seconds.", "format": "int32", "type": [ "integer", "null" ] } }, "type": "object" }, "WinnerRuleObject": { "description": "When an `automatic` step names its winner.", "properties": { "minimum_sample": { "description": "The messages every variant must have sent first.", "format": "int32", "type": "integer" }, "objective": { "$ref": "#/components/schemas/Objective", "description": "What the variants are ranked by." }, "observation_window_seconds": { "description": "How long after the revision was published the results are read.", "format": "int32", "type": "integer" } }, "required": [ "objective", "observation_window_seconds", "minimum_sample" ], "type": "object" }, "WorkspaceMode": { "description": "A workspace's mode, which its keys share: `live` reaches providers, `test` sends through a fake\ntransport only.", "enum": [ "live", "test" ], "type": "string", "x-open-enum": true }, "WorkspaceObject": { "description": "A workspace as the API shows it.", "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "deletion_requested_at": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp", "description": "When deletion was requested; the workspace is erased 30 days later." }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/Id_Workspace" }, "mode": { "$ref": "#/components/schemas/WorkspaceMode", "description": "`live` or `test`; a test workspace never reaches a provider, and its keys are `nb_test_`\nkeys. New values may be added." }, "name": { "type": "string" }, "settings": { "description": "The workspace's settings (`settings.ai`: the AI switches and budget)." }, "slug": { "type": "string" }, "timezone": { "description": "The IANA time zone of the workspace's dates.", "type": "string" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "usage": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceUsage", "description": "The current UTC month's usage: sends, people, connections and AI spend with their limits\nand `computed_at`. Present when the workspace is retrieved." }, { "type": "null" } ] }, "version": { "description": "The version `If-Match` names.", "format": "int64", "type": "integer" } }, "required": [ "id", "slug", "name", "mode", "timezone", "settings", "created_at", "updated_at", "version" ], "type": "object" }, "WorkspaceUsage": { "description": "A workspace's usage for the current UTC month.", "properties": { "ai": { "$ref": "#/components/schemas/AiSpend", "description": "AI spend this month." }, "computed_at": { "$ref": "#/components/schemas/Timestamp", "description": "When these figures were read." }, "connections": { "$ref": "#/components/schemas/Metered", "description": "Connections that are not archived." }, "month": { "$ref": "#/components/schemas/Date", "description": "The month counted, as its first day (UTC)." }, "people": { "$ref": "#/components/schemas/Metered", "description": "People in the workspace." }, "sends": { "$ref": "#/components/schemas/Metered", "description": "Messages providers accepted this month." } }, "required": [ "month", "sends", "people", "connections", "ai", "computed_at" ], "type": "object" } }, "securitySchemes": { "bearer": { "description": "An API key (`nb_live_…`, `nb_test_…`), a workspace token (`nbs_…`) or a CLI token (`nbc_…`).", "scheme": "bearer", "type": "http" }, "session": { "description": "The browser's session cookie, with the `X-CSRF-Token` header on every change.", "in": "cookie", "name": "__Host-nb_session", "type": "apiKey" } } }, "info": { "description": "One `/v1` of resources. Errors are RFC 9457 problems; lists are cursor pages; effectful requests take an `Idempotency-Key`.", "license": { "identifier": "Apache-2.0", "name": "Apache-2.0" }, "title": "Norbelys API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/v1/analytics": { "get": { "description": "Counters per UTC day from the rollup, at most about seven minutes behind; `computed_at` says\nhow far it had counted. The range defaults to the 30 days ending today and covers at most\n366 days.", "operationId": "analytics.retrieve", "parameters": [ { "description": "Only this campaign's counters.", "in": "query", "name": "campaign_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "Only this step's counters.", "in": "query", "name": "step_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Step" } }, { "description": "The first UTC day (`YYYY-MM-DD`); default 29 days before `to`.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The last UTC day, included (`YYYY-MM-DD`); default today.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "`day`, `campaign`, `step` or `variant`.", "in": "query", "name": "group_by", "required": false, "schema": { "$ref": "#/components/schemas/GroupBy" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsObject" } } }, "description": "The counters." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `analytics:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid, the range is reversed or longer than 366 days." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve the workspace's campaign counters.", "tags": [ "Reports" ] } }, "/v1/attachments": { "post": { "operationId": "attachments.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "content_base64": "SGVsbG8=", "content_type": "text/plain", "filename": "notes.txt" }, "schema": { "$ref": "#/components/schemas/Upload" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentObject" } } }, "description": "Uploaded file. Unused uploads expire after 24 hours." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires messages:send." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid filename, media type or base64; decoded data exceeds 512 KiB." } }, "security": [ { "bearer": [] } ], "summary": "Upload an immutable attachment for use in messages or replies.", "tags": [ "Messages" ] } }, "/v1/attachments/{id}": { "delete": { "operationId": "attachments.delete", "parameters": [ { "description": "Attachment id.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Attachment" } } ], "responses": { "204": { "description": "Unused attachment deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires messages:send." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No file in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The attachment is referenced by a message." } }, "security": [ { "bearer": [] } ], "summary": "Delete an unused attachment; a referenced file remains immutable.", "tags": [ "Messages" ] }, "get": { "operationId": "attachments.retrieve", "parameters": [ { "description": "Attachment id (fil_…).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Attachment" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentObject" } } }, "description": "File metadata and download link." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires the attached message's read scope, or messages:send for unused uploads." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No file in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve attachment metadata and a fresh download URL.", "tags": [ "Messages" ] } }, "/v1/campaigns": { "get": { "description": "The enrollment summary is left out too (`enrollments` is `null`): retrieving a campaign counts\nits enrollments.", "operationId": "campaigns.list", "parameters": [ { "description": "Campaigns per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Campaigns in this status.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/CampaignStatus" } }, { "description": "A prefix of the name, ignoring case.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CampaignObject" } } }, "description": "A page of campaigns." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's campaigns, newest first by default; the variants' bodies are left out.", "tags": [ "Campaigns" ] }, "post": { "operationId": "campaigns.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Q4 founders", "schedule": { "send_window": { "days": [ 1, 2, 3, 4, 5 ], "end": "17:00", "start": "09:00" }, "timezone": "Europe/Madrid" }, "senders": { "on_sender_removed": "reassign", "tags": [ "outbound" ] }, "steps": [ { "name": "Intro", "variants": [ { "html": "

Hi {{ person.given_name | default(\"there\") }},

Do you have ten minutes this week?

", "subject": "Quick question, {{ person.given_name | default(\"there\") }}" }, { "html": "

Hello,

Could we talk this week?

", "subject": "Ten minutes, {{ person.company | default(\"your team\") }}?" } ] }, { "delay_seconds": 172800, "name": "Follow-up", "variants": [ { "html": "

Any thoughts?

", "subject": "Re: quick question" } ] } ], "stop_rules": { "on_reply": "all" }, "tracking": { "clicks": true, "opens": false } }, "schema": { "$ref": "#/components/schemas/CreateCampaign" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignObject" } } }, "description": "The campaign.", "headers": { "ETag": { "description": "The campaign's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A sender identity or the tracking domain does not exist (`not_found`)." }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is larger than 1.5 MiB (`payload_too_large`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid, a template does not parse, or the steps would hold more than 1.5 MiB." } }, "security": [ { "bearer": [] } ], "summary": "Create a campaign as a `draft`, with its steps, pool, schedule, tracking and stop rules.", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}": { "delete": { "description": "A campaign that never sent is removed with its steps and enrollments; one that sent is archived,\nkept for its history, and its live enrollments are stopped.", "operationId": "campaigns.delete", "parameters": [ { "description": "The campaign id (`cmp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Campaign" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignObject" } } }, "description": "The campaign had sent: it is archived.", "headers": { "ETag": { "description": "The campaign's `version`, quoted.", "schema": { "type": "string" } } } }, "204": { "description": "The campaign had never sent: it is removed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such campaign in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Delete a campaign.", "tags": [ "Campaigns" ] }, "get": { "description": "Its enrollments are counted as it is read (`enrollments`): how many are in each status, how\nmany live ones are at each step, and when the campaign's next email may go.", "operationId": "campaigns.retrieve", "parameters": [ { "description": "The campaign id (`cmp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Campaign" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignObject" } } }, "description": "The campaign.", "headers": { "ETag": { "description": "The campaign's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such campaign in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a campaign with its steps and their variants' bodies.", "tags": [ "Campaigns" ] }, "patch": { "description": "Steps are the whole ordered list; a changed step gets a new revision for messages not yet\ncreated.", "operationId": "campaigns.update", "parameters": [ { "description": "The campaign id (`cmp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "senders": { "tags": [ "outbound", "emea" ] }, "steps": [ { "id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" }, { "delay_seconds": 259200, "id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f5" } ] }, "schema": { "$ref": "#/components/schemas/UpdateCampaign" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignObject" } } }, "description": "The campaign.", "headers": { "ETag": { "description": "The campaign's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such campaign, sender identity or tracking domain in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The campaign is archived, or a removed step has sent mail (`invalid_state`)." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is larger than 1.5 MiB (`payload_too_large`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid, a template does not parse, or the steps would hold more than 1.5 MiB; nothing changed." } }, "security": [ { "bearer": [] } ], "summary": "Change a campaign: its settings, its pool, or its steps.", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/pause": { "post": { "operationId": "campaigns.pause", "parameters": [ { "description": "The campaign id (`cmp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignObject" } } }, "description": "The campaign, `paused`.", "headers": { "ETag": { "description": "The campaign's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such campaign in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The campaign is not `active` or `materialising` (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Pause a campaign: no new message is created; queued messages wait until it is started again.", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/start": { "post": { "description": "It is `materialising` until its job makes it `active` and creates the messages already due.", "operationId": "campaigns.start", "parameters": [ { "description": "The campaign id (`cmp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignObject" } } }, "description": "The campaign, `materialising`.", "headers": { "ETag": { "description": "The campaign's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such campaign in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The campaign is not `draft` or `paused`, or has no step with a variant (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Start a campaign from `draft` or `paused`.", "tags": [ "Campaigns" ] } }, "/v1/connections": { "get": { "operationId": "connections.list", "parameters": [ { "description": "Connections per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only connections in this status.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/ConnectionStatus" } }, { "description": "Only connections of this provider.", "in": "query", "name": "provider", "required": false, "schema": { "$ref": "#/components/schemas/Provider" } }, { "description": "Only connections with an identity carrying this tag.", "in": "query", "name": "tag", "required": false, "schema": { "type": "string" } }, { "description": "Only connections naming this quota scope.", "in": "query", "name": "quota_scope_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_QuotaScope" } }, { "description": "Only connections whose account starts with this text.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ConnectionObject" } } }, "description": "A page of connections." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's connections, newest first by default.", "tags": [ "Sending" ] }, "post": { "description": "A credential-based one (SMTP, a relay, the managed MTA) is created in `verifying`, or the\nworkspace's archived connection of the same account comes back with its id, history and\nidentities; a check (or the managed MTA's provisioning) proves it. A Google or Microsoft mailbox\nanswers `202` with the consent URL; the callback creates it.", "operationId": "connections.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "account_email": "ada@example.com", "daily_limit": 50, "imap": { "host": "imap.example.com", "port": 993, "security": "tls" }, "provider": "smtp", "send_interval_minutes": 10, "smtp": { "host": "smtp.example.com", "password": "app-password", "port": 587, "security": "starttls" } }, "schema": { "$ref": "#/components/schemas/CreateConnection" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionObject" } } }, "description": "The connection, `verifying`.", "headers": { "ETag": { "description": "The connection's `version`, quoted.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentAnswer" } } }, "description": "Google or Microsoft: the consent to open, with the ceremony cookie." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such quota scope in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The account is connected already (`conflict`), naming the live connection." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a connection.", "tags": [ "Sending" ] } }, "/v1/connections/{id}": { "delete": { "description": "It stops sending, its credential is erased and its folders are no longer read, while its history\nstays readable and its provider webhook keeps receiving late evidence. Connecting the same\naccount again restores it.", "operationId": "connections.delete", "parameters": [ { "description": "The connection id (`con_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Connection" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionObject" } } }, "description": "The archived connection.", "headers": { "ETag": { "description": "The connection's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`, or a member does not own the connection." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such connection in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Archive a connection.", "tags": [ "Sending" ] }, "get": { "operationId": "connections.retrieve", "parameters": [ { "description": "The connection id (`con_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Connection" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionObject" } } }, "description": "The connection.", "headers": { "ETag": { "description": "The connection's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such connection in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a connection.", "tags": [ "Sending" ] }, "patch": { "description": "Pause or resume it, change its pacing, identities or folders, or give it a new credential (then\nit is verified again).", "operationId": "connections.update", "parameters": [ { "description": "The connection id (`con_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "paused": true }, "schema": { "$ref": "#/components/schemas/UpdateConnection" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionObject" } } }, "description": "The connection.", "headers": { "ETag": { "description": "The connection's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`, or a member does not own the connection." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such connection in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The connection is archived (`invalid_state`), or an identity's address belongs to another connection (`conflict`)." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Update a connection.", "tags": [ "Sending" ] } }, "/v1/connections/{id}/verify": { "post": { "description": "It becomes `verifying` and its check runs (the managed MTA's provisioning, for a `norbelys`\nconnection). For an OAuth connection whose grant is lost, the answer carries `authorization.url`\nfor the browser instead, and the ceremony cookie.", "operationId": "connections.verify", "parameters": [ { "description": "The connection id (`con_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "OAuth: the dashboard path the browser returns to after the consent.", "in": "query", "name": "return_to", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionObject" } } }, "description": "The connection, `verifying`, or with `authorization` when consent is needed.", "headers": { "ETag": { "description": "The connection's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`, or a member does not own the connection." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such connection in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The connection is archived (`invalid_state`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The return path is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Verify a connection now.", "tags": [ "Sending" ] } }, "/v1/delivery_events": { "get": { "operationId": "delivery_events.list", "parameters": [ { "description": "Events per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Events about this message.", "in": "query", "name": "message_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Message" } }, { "description": "Events about this campaign's messages.", "in": "query", "name": "campaign_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "Events about messages to this person.", "in": "query", "name": "person_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Person" } }, { "description": "Events of this kind.", "in": "query", "name": "kind", "required": false, "schema": { "$ref": "#/components/schemas/DeliveryEventKind" } }, { "description": "Events about this recipient (ignoring ASCII case).", "in": "query", "name": "recipient", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DeliveryEventObject" } } }, "description": "A page of delivery events." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's delivery events, newest first by default.", "tags": [ "Messages" ] } }, "/v1/delivery_events/{id}": { "get": { "operationId": "delivery_events.retrieve", "parameters": [ { "description": "The delivery event id (`dev_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_DeliveryEvent" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEventObject" } } }, "description": "The delivery event." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such delivery event in this workspace (`not_found`), or its period was archived (`archived`): `POST /v1/exports` reads it." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a delivery event.", "tags": [ "Messages" ] } }, "/v1/enrollments": { "get": { "operationId": "enrollments.list", "parameters": [ { "description": "Enrollments per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000: with `sender_identity_id` and `status=active`, what removing a sender would touch.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Enrollments of this campaign.", "in": "query", "name": "campaign_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "Enrollments of this person.", "in": "query", "name": "person_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Person" } }, { "description": "Conversations kept by this sender.", "in": "query", "name": "sender_identity_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_SenderIdentity" } }, { "description": "Enrollments in this status.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/EnrollmentStatus" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_EnrollmentObject" } } }, "description": "A page of enrollments." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's enrollments, newest first by default.", "tags": [ "Campaigns" ] }, "post": { "description": "Up to 100 at once (`201`), more through a job (`202`). Unknown people, suppressed addresses and\npeople already enrolled are skipped.", "operationId": "enrollments.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "campaign_id": "cmp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4", "group_id": "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" }, "schema": { "$ref": "#/components/schemas/CreateEnrollments" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrolled" } } }, "description": "Up to 100 people: the enrollments made and the people skipped." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobObject" } } }, "description": "More than 100 people: the `enrollment.add` job; `Location` names it.", "headers": { "Location": { "description": "The job's path.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such campaign, group or segment in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The campaign is archived (`invalid_state`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid, or names no source of people or more than one." } }, "security": [ { "bearer": [] } ], "summary": "Enroll people into a campaign.", "tags": [ "Campaigns" ] } }, "/v1/enrollments/{id}": { "get": { "description": "Its person, position, next run, status and the sender its conversation keeps or waits for.", "operationId": "enrollments.retrieve", "parameters": [ { "description": "The enrollment id (`enr_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Enrollment" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentObject" } } }, "description": "The enrollment." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such enrollment in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an enrollment.", "tags": [ "Campaigns" ] } }, "/v1/enrollments/{id}/stop": { "post": { "operationId": "enrollments.stop", "parameters": [ { "description": "The enrollment id (`enr_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Enrollment" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentObject" } } }, "description": "The enrollment, `stopped`." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such enrollment in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The enrollment already ended (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Stop an enrollment: no further step runs, and its message still queued is cancelled.", "tags": [ "Campaigns" ] } }, "/v1/events": { "get": { "description": "With `after`, only later events, in ascending order unless `order` says otherwise; with `wait`,\nan empty page waits up to that many seconds (at most 25) for an event to arrive.", "operationId": "events.list", "parameters": [ { "description": "Events per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` or `asc`; `asc` by default with `after`, `desc` otherwise.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only events of this type.", "in": "query", "name": "type", "required": false, "schema": { "$ref": "#/components/schemas/EventType" } }, { "description": "Only events after this one.", "in": "query", "name": "after", "required": false, "schema": { "$ref": "#/components/schemas/Id_OutboxEvent" } }, { "description": "Seconds to wait for a first event when the page would be empty, 0 to 25.", "in": "query", "name": "wait", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_EventObject" } } }, "description": "A page of events." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's events, newest first by default.", "tags": [ "Automation" ] }, "post": { "description": "It is delivered like any other event, to every subscribed endpoint, or only to\n`webhook_endpoint_id` when given.", "operationId": "events.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "type": "endpoint.test", "webhook_endpoint_id": "whe_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" }, "schema": { "$ref": "#/components/schemas/CreateEvent" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventObject" } } }, "description": "The synthetic event; its deliveries appear within seconds." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such endpoint in this workspace." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a synthetic event with sample data of its type.", "tags": [ "Automation" ] } }, "/v1/events/{id}": { "get": { "operationId": "events.retrieve", "parameters": [ { "description": "The event id (`evt_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_OutboxEvent" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventObject" } } }, "description": "The event." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such event in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an event.", "tags": [ "Automation" ] } }, "/v1/exports": { "get": { "operationId": "exports.list", "parameters": [ { "description": "Exports per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only exports in this stored status (an expired export matches `ready`).", "in": "query", "name": "status", "required": false, "schema": { "description": "The status filter of `GET /exports`, on the stored status: an export whose file has expired\nstill matches its stored status (`ready`), and reads as `expired`.", "enum": [ "queued", "running", "ready", "failed" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ExportObject" } } }, "description": "A page of exports." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's exports, newest first by default.", "tags": [ "Audience" ] }, "post": { "description": "The export runs as a job: poll the export for its link, or listen for `export.completed`.\nHistory (`messages`, `attempts`, `delivery_events`, `inbound_messages`) includes the periods\nalready archived out of the database.", "operationId": "exports.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "filters": { "group_id": "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" }, "format": "csv", "resource": "people" }, "schema": { "$ref": "#/components/schemas/CreateExport" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportObject" } } }, "description": "The export, queued; `Location` names it.", "headers": { "Location": { "description": "The export's path.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write` (people), `messages:read` (messages, attempts, delivery events) or `inbox:read` (inbound messages)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The filters name a group or segment that does not exist." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Export a resource's list to a file.", "tags": [ "Audience" ] } }, "/v1/exports/{id}": { "get": { "operationId": "exports.retrieve", "parameters": [ { "description": "The export id (`exp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Export" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportObject" } } }, "description": "The export." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks the scope that reads the export's resource: `people:read`, `messages:read` (messages, attempts, delivery events) or `inbox:read` (inbound messages)." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such export in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an export, with a fresh download link when it is ready.", "tags": [ "Audience" ] } }, "/v1/fields": { "get": { "operationId": "fields.list", "parameters": [ { "description": "Fields per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_FieldObject" } } }, "description": "A page of fields." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's custom fields (at most 100).", "tags": [ "Audience" ] }, "post": { "operationId": "fields.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "key": "tier", "label": "Tier", "options": [ "gold", "silver" ], "type": "enum" }, "schema": { "$ref": "#/components/schemas/CreateField" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldObject" } } }, "description": "The field.", "headers": { "ETag": { "description": "The field's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The key is taken (`conflict`), or the workspace has 100 fields (`invalid_state`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a custom field.", "tags": [ "Audience" ] } }, "/v1/fields/{id}": { "delete": { "description": "A field a segment uses cannot be deleted.", "operationId": "fields.delete", "parameters": [ { "description": "The field id (`fld_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Field" } } ], "responses": { "204": { "description": "The field and its values are deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such field in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A segment uses the field (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Delete a custom field and every person's value of it.", "tags": [ "Audience" ] }, "patch": { "operationId": "fields.update", "parameters": [ { "description": "The field id (`fld_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Field" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "options": [ "gold", "silver", "bronze" ] }, "schema": { "$ref": "#/components/schemas/UpdateField" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldObject" } } }, "description": "The field.", "headers": { "ETag": { "description": "The field's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such field in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Options on a field that is not an enum, or a removed option still in use (`invalid_state`)." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Update a custom field's label or an enum's options. Its key and type never change.", "tags": [ "Audience" ] } }, "/v1/groups": { "get": { "operationId": "groups.list", "parameters": [ { "description": "Groups per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "A prefix of the name, ignoring case.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_GroupObject" } } }, "description": "A page of groups." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's groups, newest first by default, each with its people counted.", "tags": [ "Audience" ] }, "post": { "operationId": "groups.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "description": "Met at the 2026 summit", "name": "Conference leads" }, "schema": { "$ref": "#/components/schemas/CreateGroup" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupObject" } } }, "description": "The group.", "headers": { "ETag": { "description": "The group's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create an empty group.", "tags": [ "Audience" ] } }, "/v1/groups/{id}": { "delete": { "operationId": "groups.delete", "parameters": [ { "description": "The group id (`grp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Group" } } ], "responses": { "204": { "description": "The group is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such group in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Delete a group and its memberships; its people stay.", "tags": [ "Audience" ] }, "get": { "operationId": "groups.retrieve", "parameters": [ { "description": "The group id (`grp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Group" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupObject" } } }, "description": "The group.", "headers": { "ETag": { "description": "The group's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such group in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a group with its people counted.", "tags": [ "Audience" ] }, "patch": { "operationId": "groups.update", "parameters": [ { "description": "The group id (`grp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Group" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Summit leads" }, "schema": { "$ref": "#/components/schemas/UpdateGroup" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupObject" } } }, "description": "The group.", "headers": { "ETag": { "description": "The group's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such group in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Rename a group or change its description.", "tags": [ "Audience" ] } }, "/v1/images": { "post": { "description": "The file is the body, sent with its own `Content-Type` (`image/png`, `image/jpeg`, `image/gif`\nor `image/webp`), at most 16 MiB; its first bytes must be that format. The answer carries the\nimage's public URL, to use in a message's or a variant's HTML.", "operationId": "images.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "image/gif": { "example": "(the GIF file's bytes)", "schema": { "type": "string" } }, "image/jpeg": { "example": "(the JPEG file's bytes)", "schema": { "type": "string" } }, "image/png": { "example": "(the PNG file's bytes)", "schema": { "type": "string" } }, "image/webp": { "example": "(the WebP file's bytes)", "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageObject" } } }, "description": "The image, with its public URL." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The file is larger than 16 MiB." }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not sent as a PNG, JPEG, GIF or WebP image." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The file is empty, or its content is not the format its `Content-Type` names." }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Object storage is unavailable; retry with the same key." } }, "security": [ { "bearer": [] } ], "summary": "Upload an image to show in mail.", "tags": [ "Content" ] } }, "/v1/images/{id}": { "delete": { "description": "Its public URL stops answering; mail already sent shows it no more, except where a cache kept a\ncopy.", "operationId": "images.delete", "parameters": [ { "description": "The image id (`img_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Image" } } ], "responses": { "204": { "description": "The image is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `campaigns:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such image in this workspace." }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Object storage is unavailable; retry." } }, "security": [ { "bearer": [] } ], "summary": "Delete an image.", "tags": [ "Content" ] } }, "/v1/imports": { "get": { "operationId": "imports.list", "parameters": [ { "description": "Imports per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only imports in this status.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/ImportStatus" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ImportObject" } } }, "description": "A page of imports." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's imports, newest first by default.", "tags": [ "Audience" ] }, "post": { "description": "A CSV file is the body (`Content-Type: text/csv`, at most 16 MiB, its first record the header;\n`group_id` as a query parameter); JSON names up to 1,000 `people`. The import runs as a job:\npoll the import, or listen for `import.completed`.", "operationId": "imports.create", "parameters": [ { "description": "With a CSV body: the group every imported person joins.", "in": "query", "name": "group_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Group" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "group_id": "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4", "people": [ { "email": "ada@example.com", "fields": { "tier": "gold" }, "given_name": "Ada" } ] }, "schema": { "$ref": "#/components/schemas/CreateImport" } }, "text/csv": { "example": "email,first_name,company,tier\nada@example.com,Ada,Analytical,gold\n", "schema": { "type": "string" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportObject" } } }, "description": "The import, queued; `Location` names it.", "headers": { "Location": { "description": "The import's path.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The group does not exist (`not_found`)." }, "413": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The file is larger than 16 MiB." }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is neither `text/csv` nor `application/json`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid, or the file has no email column." }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Object storage is unavailable; retry with the same key." } }, "security": [ { "bearer": [] } ], "summary": "Import people from a CSV file or from JSON.", "tags": [ "Audience" ] } }, "/v1/imports/{id}": { "get": { "operationId": "imports.retrieve", "parameters": [ { "description": "The import id (`imp_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Import" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportObject" } } }, "description": "The import." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such import in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an import: its status, counts, first problems and the link to its error report.", "tags": [ "Audience" ] } }, "/v1/inbound_messages": { "get": { "operationId": "inbound_messages.list", "parameters": [ { "description": "Messages per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Messages of this thread.", "in": "query", "name": "thread_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Thread" } }, { "description": "Messages read from this connection's mailbox.", "in": "query", "name": "connection_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "Messages of this classification.", "in": "query", "name": "classification", "required": false, "schema": { "$ref": "#/components/schemas/InboundClassification" } }, { "description": "`true`: waiting for a person's decision.", "in": "query", "name": "review_requested", "required": false, "schema": { "type": "boolean" } }, { "description": "Received at or after this instant (RFC 3339).", "in": "query", "name": "received_at[gte]", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_InboundMessageObject" } } }, "description": "A page of inbound messages." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the messages the inbox read, newest first by default.", "tags": [ "Inbox" ] } }, "/v1/inbound_messages/{id}": { "get": { "operationId": "inbound_messages.retrieve", "parameters": [ { "description": "The inbound message id (`inb_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_InboundMessage" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundMessageObject" } } }, "description": "The inbound message.", "headers": { "ETag": { "description": "The message's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such inbound message in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a message the inbox read.", "tags": [ "Inbox" ] }, "patch": { "operationId": "inbound_messages.update", "parameters": [ { "description": "The inbound message id (`inb_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_InboundMessage" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "classification": "human_reply", "sentiment": "positive" }, "schema": { "$ref": "#/components/schemas/UpdateInbound" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundMessageObject" } } }, "description": "The inbound message.", "headers": { "ETag": { "description": "The message's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such inbound message in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Correct a message's classification or sentiment by hand; AI never overrides it afterwards.", "tags": [ "Inbox" ] } }, "/v1/inbound_messages/{id}/content": { "get": { "operationId": "inbound_messages.content", "parameters": [ { "description": "Inbound message id.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_InboundMessage" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageContent" } } }, "description": "Retained content." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires inbox:read." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No retained message." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve full received content and available attachments, with truncation explicit.", "tags": [ "Inbox" ] } }, "/v1/inbound_messages/{id}/review": { "post": { "description": "Confirming applies it: a suppression, or moving the person to the new address a notice gave.", "operationId": "inbound_messages.review", "parameters": [ { "description": "The inbound message id (`inb_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_InboundMessage" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "decision": "confirm" }, "schema": { "$ref": "#/components/schemas/Review" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundMessageObject" } } }, "description": "The inbound message, with the decision.", "headers": { "ETag": { "description": "The message's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No `Idempotency-Key`, or the body is not JSON." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such inbound message in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No review was asked for, or it was decided already (`invalid_state`); or the new address belongs to another person (`conflict`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Confirm or dismiss what an inbound message proposed.", "tags": [ "Inbox" ] } }, "/v1/jobs/{id}": { "get": { "operationId": "jobs.retrieve", "parameters": [ { "description": "The job id (`job_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Job" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobObject" } } }, "description": "The job." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such job in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a job of the credential's workspace.", "tags": [ "Automation" ] } }, "/v1/jobs/{id}/cancel": { "post": { "description": "A waiting job is cancelled at once, a running one at its next chunk boundary.", "operationId": "jobs.cancel", "parameters": [ { "description": "The job id (`job_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Job" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobObject" } } }, "description": "The job, cancelled or with its cancellation requested." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such job in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The job already ended (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Request the cancellation of a job.", "tags": [ "Automation" ] } }, "/v1/messages": { "get": { "operationId": "messages.list", "parameters": [ { "description": "Messages per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Messages of this campaign.", "in": "query", "name": "campaign_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "Messages of this enrollment.", "in": "query", "name": "enrollment_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Enrollment" } }, { "description": "Messages to this person.", "in": "query", "name": "person_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Person" } }, { "description": "Messages sent through this connection.", "in": "query", "name": "connection_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "Messages of this thread.", "in": "query", "name": "thread_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Thread" } }, { "description": "Messages in this state.", "in": "query", "name": "state", "required": false, "schema": { "$ref": "#/components/schemas/MessageState" } }, { "description": "Created at or after this instant (RFC 3339).", "in": "query", "name": "created_at[gte]", "required": false, "schema": { "type": "string" } }, { "description": "Created after this instant.", "in": "query", "name": "created_at[gt]", "required": false, "schema": { "type": "string" } }, { "description": "Created at or before this instant.", "in": "query", "name": "created_at[lte]", "required": false, "schema": { "type": "string" } }, { "description": "Created before this instant.", "in": "query", "name": "created_at[lt]", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_MessageObject" } } }, "description": "A page of messages." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's messages, newest first by default.", "tags": [ "Messages" ] }, "post": { "description": "Four forms: a direct message with its own content; a reply in a thread (`thread_id` and a\nbody), sent from the thread's identity to the sender of its latest inbound message unless `to`\nsays otherwise; or a campaign step's content (`step_id` or `variant_id`) for people who are not\nenrolled, with `person_id` (and `to` to preview that person's version at another address),\nanswered with the message, or with up to 100 `person_ids`, answered per person.", "operationId": "messages.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Direct": { "summary": "A message with its own content", "value": { "from": "max@acme.example", "html": "

Hi {{ variables.first_name }},

Do you have ten minutes this week?

", "send_at": "2026-10-02T09:00:00Z", "subject": "Quick question, {{ variables.first_name }}", "to": [ "ada@example.com" ], "variables": { "first_name": "Ada" } } }, "Reply": { "summary": "An answer in a thread, from the thread's identity", "value": { "html": "

Thanks Ada, Tuesday at 10 works for me.

", "thread_id": "thr_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" } }, "Step for several people": { "summary": "A step's content for people who are not enrolled, a result each", "value": { "person_ids": [ "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4", "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f5" ], "step_id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" } }, "Step preview": { "summary": "One person's version of a step, sent to another address", "value": { "person_id": "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4", "step_id": "stp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4", "to": "max@acme.example" } } }, "schema": { "$ref": "#/components/schemas/MessageForm" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesCreated" } } }, "description": "The message, queued; `Location` names it. For `person_ids`, a result per person.", "headers": { "Location": { "description": "The message's path (one message).", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No `Idempotency-Key`, or malformed JSON." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:send`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such sender identity, step, variant or person in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The sender identity is disabled, or the campaign's pool has no usable sender (`invalid_state`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid (`validation_failed`, with a pointer per field and per template), or a recipient is suppressed (`suppressed`)." } }, "security": [ { "bearer": [] } ], "summary": "Send a message: it is queued now and sent when due, outside any campaign's cadence.", "tags": [ "Messages" ], "x-norbelys-overloads": [ { "request": { "$ref": "#/components/schemas/CreateMessage" }, "response": { "$ref": "#/components/schemas/MessageObject" } }, { "request": { "$ref": "#/components/schemas/CreateReply" }, "response": { "$ref": "#/components/schemas/MessageObject" } }, { "request": { "$ref": "#/components/schemas/CreateStepMessage" }, "response": { "$ref": "#/components/schemas/MessageObject" } }, { "request": { "$ref": "#/components/schemas/CreateStepMessages" }, "response": { "$ref": "#/components/schemas/StepResults" } } ] } }, "/v1/messages/search": { "get": { "operationId": "messages.search", "parameters": [ { "description": "Literal case-insensitive substring, 2 to 256 characters. Absent: history.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Only this conversation.", "in": "query", "name": "thread_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Thread" } }, { "description": "Only this connection.", "in": "query", "name": "connection_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "Inbound, outbound, or both when absent.", "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction" } }, { "description": "Inclusive ingestion instant.", "in": "query", "name": "from", "required": false, "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "description": "Exclusive ingestion instant.", "in": "query", "name": "to", "required": false, "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "description": "1 to 100, default 20.", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Signed cursor from the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Ingestion order, descending by default.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_HistoryMessage" } } }, "description": "A page of retained history." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid cursor." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires messages:read for outbound and inbox:read for inbound; both when direction is absent." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid search or date bounds." } }, "security": [ { "bearer": [] } ], "summary": "Search complete retained content, or list history when q is absent.", "tags": [ "Messages" ] } }, "/v1/messages/{id}": { "get": { "operationId": "messages.retrieve", "parameters": [ { "description": "The message id (`msg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Message" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageObject" } } }, "description": "The message." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such message in this workspace (`not_found`), or its period was archived (`archived`): `POST /v1/exports` reads it." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a message, with its latest attempts, its first delivery events and its holds.", "tags": [ "Messages" ] } }, "/v1/messages/{id}/cancel": { "post": { "description": "Only a `queued` message can be cancelled: one a sender has claimed or started is on its way\nand cannot be recalled (`409 invalid_state`), and a sent, failed or cancelled one has nothing\nleft to cancel. The message becomes `cancelled` and `message.cancelled` is sent to the\nworkspace's webhook endpoints.", "operationId": "messages.cancel", "parameters": [ { "description": "The message id (`msg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Message" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageObject" } } }, "description": "The message, cancelled." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No `Idempotency-Key`." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:send`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such message in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The message is not queued (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Cancel a queued message.", "tags": [ "Messages" ] } }, "/v1/messages/{id}/content": { "get": { "operationId": "messages.content", "parameters": [ { "description": "Message id.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Message" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageContent" } } }, "description": "Retained content." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires messages:read." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No retained message." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an outbound message's retained authored or last prepared content.", "tags": [ "Messages" ] } }, "/v1/messages/{id}/release_holds": { "post": { "description": "A recipient is held when evidence about this message said its mailbox was full, its server\nasked to come back later, or its domain had no mail route: mail to the address waits until a\nlater success of the message lifts the hold, the hold's time runs out, or a person who knows\nbetter releases it here. Every open hold of the message is resolved as `manual`, so mail to\nthose addresses flows again, and the evidence is kept in the workspace's audit log. A message\nwithout open holds is answered as it is.", "operationId": "messages.release_holds", "parameters": [ { "description": "The message id (`msg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Message" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "evidence": "The recipient confirmed by phone that their mailbox has room again." }, "schema": { "$ref": "#/components/schemas/ReleaseHolds" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageObject" } } }, "description": "The message, its holds released." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No `Idempotency-Key`, or malformed JSON." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:send`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such message in this workspace." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid (`validation_failed`)." } }, "security": [ { "bearer": [] } ], "summary": "Release a message's holds.", "tags": [ "Messages" ] } }, "/v1/messages/{id}/resolve": { "post": { "description": "A message is `uncertain` when its submission ended without a readable final answer: the\nprovider may have taken it, so it is never sent again automatically. A person who knows what\nhappened settles it here, as `sent` or `failed`, with the evidence; the decision is recorded\nas a `manual` delivery event, the counters follow, and `message.sent` or `message.failed` is\nsent to the workspace's webhook endpoints. Only an `uncertain` message can be resolved\n(`409 invalid_state`).", "operationId": "messages.resolve", "parameters": [ { "description": "The message id (`msg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Message" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "evidence": "Found in the mailbox's Sent folder on 2026-10-02 at 09:14 UTC.", "state": "sent" }, "schema": { "$ref": "#/components/schemas/ResolveMessage" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageObject" } } }, "description": "The message, resolved." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No `Idempotency-Key`, or malformed JSON." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `messages:send`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such message in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The message is not uncertain (`invalid_state`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid (`validation_failed`)." } }, "security": [ { "bearer": [] } ], "summary": "Resolve an uncertain message.", "tags": [ "Messages" ] } }, "/v1/metrics": { "get": { "operationId": "metrics.retrieve", "parameters": [ { "description": "events (default), rates, or usage.", "in": "query", "name": "family", "required": false, "schema": { "$ref": "#/components/schemas/Family" } }, { "description": "Inclusive first UTC date; default 29 days before to.", "in": "query", "name": "from", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "description": "Inclusive last UTC date; default today. Maximum range: 366 days.", "in": "query", "name": "to", "required": false, "schema": { "$ref": "#/components/schemas/Date" } }, { "description": "Filter events or rates by connection.", "in": "query", "name": "connection_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "Filter events or rates by campaign.", "in": "query", "name": "campaign_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Campaign" } }, { "description": "campaign, direct, reply or transactional.", "in": "query", "name": "kind", "required": false, "schema": { "$ref": "#/components/schemas/MessageKind" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metrics" } } }, "description": "Metrics and their freshness." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Requires analytics:read." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid dates, range, or filters for usage." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve daily counts, rates or current workspace usage.", "tags": [ "Reports" ] } }, "/v1/people": { "get": { "description": "With `segment_id`, the people the segment's filter matches now.", "operationId": "people.list", "parameters": [ { "description": "People per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "`id` (default, the creation order) or `updated_at` (when each person last changed); ties are ordered by id.", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "The person with this address (ignoring ASCII case).", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Members of this group.", "in": "query", "name": "group_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Group" } }, { "description": "People this segment matches.", "in": "query", "name": "segment_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Segment" } }, { "description": "A prefix of the address, a name or the company, ignoring case.", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Created at or after this instant (RFC 3339).", "in": "query", "name": "created_at[gte]", "required": false, "schema": { "type": "string" } }, { "description": "Created after this instant.", "in": "query", "name": "created_at[gt]", "required": false, "schema": { "type": "string" } }, { "description": "Created at or before this instant.", "in": "query", "name": "created_at[lte]", "required": false, "schema": { "type": "string" } }, { "description": "Created before this instant.", "in": "query", "name": "created_at[lt]", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PersonObject" } } }, "description": "A page of people." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such group or segment in this workspace." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's people, newest first by default.", "tags": [ "Audience" ] }, "post": { "operationId": "people.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "company": "Analytical", "email": "ada@example.com", "fields": { "industry": "Computing" }, "given_name": "Ada" }, "schema": { "$ref": "#/components/schemas/CreatePerson" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonObject" } } }, "description": "The person.", "headers": { "ETag": { "description": "The person's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A group does not exist (`not_found`)." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A person with this address exists (`conflict`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a person.", "tags": [ "Audience" ] } }, "/v1/people/{id}": { "delete": { "description": "A person with enrollments or messages cannot be deleted: its history refers to it.", "operationId": "people.delete", "parameters": [ { "description": "The person id (`per_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Person" } } ], "responses": { "204": { "description": "The person is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such person in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The person has enrollments or messages (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Delete a person and its memberships.", "tags": [ "Audience" ] }, "get": { "operationId": "people.retrieve", "parameters": [ { "description": "The person id (`per_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Person" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonObject" } } }, "description": "The person.", "headers": { "ETag": { "description": "The person's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such person in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a person.", "tags": [ "Audience" ] }, "patch": { "operationId": "people.update", "parameters": [ { "description": "The person id (`per_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Person" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "company": "Analytical Engines", "fields": { "industry": null }, "group_ids": [ "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4" ] }, "schema": { "$ref": "#/components/schemas/UpdatePerson" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonObject" } } }, "description": "The person.", "headers": { "ETag": { "description": "The person's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such person, or a group does not exist." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Another person has the new address (`conflict`)." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Update a person: its address, names, company, custom values (merged) or groups (replaced).", "tags": [ "Audience" ] } }, "/v1/preflight": { "post": { "description": "Syntax, DNS routing (MX, an implicit MX, or a null MX that refuses all mail), and the\nworkspace's suppressions and holds. When configured, the remote mail host also checks SMTP\nrecipient acceptance without sending a message. Nothing is stored. SMTP acceptance is not\nproof of delivery; unavailable checks are skipped. A route the workspace's sending found in\nDNS within the last day is answered\nfrom that, as the sender reads it; any other is asked of DNS now, and a lookup DNS could not\nanswer is `unknown`. In a test-mode workspace only the syntax is checked, as its sender does:\nits mail never leaves the fake transport. SMTP checks share a 15-second budget; use batches\nof at most eight addresses to avoid skipping addresses when that budget expires.", "operationId": "preflight.create", "requestBody": { "content": { "application/json": { "example": { "emails": [ "ada@example.com", "not-an-address" ] }, "schema": { "$ref": "#/components/schemas/CreatePreflight" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightResult" } } }, "description": "One finding per address." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Check addresses before mailing them.", "tags": [ "Audience" ] } }, "/v1/quota_scopes": { "get": { "operationId": "quota_scopes.list", "parameters": [ { "description": "Scopes per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only scopes of this provider.", "in": "query", "name": "provider", "required": false, "schema": { "$ref": "#/components/schemas/Provider" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_QuotaScopeObject" } } }, "description": "A page of quota scopes." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's quota scopes, newest first by default.", "tags": [ "Sending" ] }, "post": { "operationId": "quota_scopes.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "messages_per_day": 50000, "provider": "ses", "scope_key": "123456789012:eu-west-1", "window_limit": 14, "window_seconds": 1, "window_unit": "recipients" }, "schema": { "$ref": "#/components/schemas/CreateQuotaScope" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaScopeObject" } } }, "description": "The quota scope.", "headers": { "ETag": { "description": "The quota scope's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The workspace has a scope of this provider and key (`conflict`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a quota scope.", "tags": [ "Sending" ] } }, "/v1/quota_scopes/{id}": { "delete": { "description": "Its connections keep running without one. Refused while SES connections, archived ones included,\nname it.", "operationId": "quota_scopes.delete", "parameters": [ { "description": "The quota scope id (`qsc_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_QuotaScope" } } ], "responses": { "204": { "description": "The quota scope is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such quota scope in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "SES connections name it (`invalid_state`), named in `detail`." } }, "security": [ { "bearer": [] } ], "summary": "Delete a quota scope and its ledger.", "tags": [ "Sending" ] }, "get": { "operationId": "quota_scopes.retrieve", "parameters": [ { "description": "The quota scope id (`qsc_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_QuotaScope" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaScopeObject" } } }, "description": "The quota scope.", "headers": { "ETag": { "description": "The quota scope's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such quota scope in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a quota scope.", "tags": [ "Sending" ] }, "patch": { "operationId": "quota_scopes.update", "parameters": [ { "description": "The quota scope id (`qsc_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_QuotaScope" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "messages_per_day": 100000, "window_limit": null, "window_seconds": null, "window_unit": null }, "schema": { "$ref": "#/components/schemas/UpdateQuotaScope" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaScopeObject" } } }, "description": "The quota scope.", "headers": { "ETag": { "description": "The quota scope's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such quota scope in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Update a quota scope's limits: each limit given replaces the stored one, `null` clears it.", "tags": [ "Sending" ] } }, "/v1/segments": { "get": { "operationId": "segments.list", "parameters": [ { "description": "Segments per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SegmentObject" } } }, "description": "A page of segments." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's segments, newest first by default. A list leaves the counts out.", "tags": [ "Audience" ] }, "post": { "operationId": "segments.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "filter": { "conditions": [ { "field": "fields.tier", "operator": "equals", "value": "gold" }, { "field": "email_domain", "operator": "not_equals", "value": "gmail.com" } ], "match": "all" }, "name": "Gold accounts" }, "schema": { "$ref": "#/components/schemas/CreateSegment" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentObject" } } }, "description": "The segment.", "headers": { "ETag": { "description": "The segment's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body or the filter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a segment; the response counts its people.", "tags": [ "Audience" ] } }, "/v1/segments/{id}": { "delete": { "operationId": "segments.delete", "parameters": [ { "description": "The segment id (`seg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Segment" } } ], "responses": { "204": { "description": "The segment is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such segment in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Delete a segment; its people stay.", "tags": [ "Audience" ] }, "get": { "operationId": "segments.retrieve", "parameters": [ { "description": "The segment id (`seg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Segment" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentObject" } } }, "description": "The segment.", "headers": { "ETag": { "description": "The segment's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such segment in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a segment with its people counted now (up to 10,000).", "tags": [ "Audience" ] }, "patch": { "operationId": "segments.update", "parameters": [ { "description": "The segment id (`seg_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Segment" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "filter": { "conditions": [ { "field": "fields.tier", "operator": "in", "value": [ "gold", "silver" ] } ] }, "name": "Gold and silver" }, "schema": { "$ref": "#/components/schemas/UpdateSegment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentObject" } } }, "description": "The segment.", "headers": { "ETag": { "description": "The segment's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such segment in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body or the filter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Rename a segment or replace its filter.", "tags": [ "Audience" ] } }, "/v1/sending_domains": { "get": { "operationId": "sending_domains.list", "parameters": [ { "description": "Domains per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only domains in this status.", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/SendingDomainStatus" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DomainObject" } } }, "description": "A page of sending domains." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's sending domains, newest first by default.", "tags": [ "Sending" ] }, "post": { "operationId": "sending_domains.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "hostname": "example.com", "purpose": "send_receive", "tracking_hostname": "links.example.com" }, "schema": { "$ref": "#/components/schemas/CreateDomain" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } }, "description": "The domain with its records.", "headers": { "ETag": { "description": "The domain's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The workspace has this hostname already (`conflict`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a sending domain, `pending_verification`, with the DNS records to publish.", "tags": [ "Sending" ] } }, "/v1/sending_domains/{id}": { "delete": { "operationId": "sending_domains.delete", "parameters": [ { "description": "The sending domain id (`dom_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_SendingDomain" } } ], "responses": { "204": { "description": "The domain is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such sending domain in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Delete a sending domain.", "tags": [ "Sending" ] }, "get": { "operationId": "sending_domains.retrieve", "parameters": [ { "description": "The sending domain id (`dom_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_SendingDomain" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } }, "description": "The domain.", "headers": { "ETag": { "description": "The domain's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such sending domain in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a sending domain.", "tags": [ "Sending" ] }, "patch": { "operationId": "sending_domains.update", "parameters": [ { "description": "The sending domain id (`dom_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_SendingDomain" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "purpose": "send", "tracking_hostname": "links.example.com" }, "schema": { "$ref": "#/components/schemas/UpdateDomain" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } }, "description": "The domain.", "headers": { "ETag": { "description": "The domain's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such sending domain in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Update a domain's use and its optional separate tracking hostname.", "tags": [ "Sending" ] } }, "/v1/sending_domains/{id}/verify": { "post": { "operationId": "sending_domains.verify", "parameters": [ { "description": "The sending domain id (`dom_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_SendingDomain" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainObject" } } }, "description": "The domain, `verifying`.", "headers": { "ETag": { "description": "The domain's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `connections:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such sending domain in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Another workspace holds the hostname (`conflict`)." } }, "security": [ { "bearer": [] } ], "summary": "Verify a sending domain now: it becomes `verifying` and its DNS records are checked.", "tags": [ "Sending" ] } }, "/v1/smtp_authorization": { "get": { "operationId": "smtp_authorization.retrieve", "parameters": [ { "description": "The connected sending domain used as the SMTP username.", "in": "query", "name": "domain", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmtpAuthorization" } } }, "description": "The tenant-scoped SMTP authorization." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A live API key with messages:send is required." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No active sending service for this domain." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The domain is not enabled for sending." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The domain is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Authenticate SMTP submission using the same live API key as HTTP sending.", "tags": [ "Sending" ] } }, "/v1/suppressions": { "get": { "operationId": "suppressions.list", "parameters": [ { "description": "Suppressions per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "The suppression of this address (ignoring ASCII case).", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Only suppressions for this reason.", "in": "query", "name": "reason", "required": false, "schema": { "$ref": "#/components/schemas/SuppressionReason" } }, { "description": "Only suppressions from this source.", "in": "query", "name": "source", "required": false, "schema": { "$ref": "#/components/schemas/SuppressionSource" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_SuppressionObject" } } }, "description": "A page of suppressions." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's suppressions, newest first by default.", "tags": [ "Audience" ] }, "post": { "description": "Two forms. `email` suppresses one address and answers the suppression (`201`), or `409` when\nit is suppressed already. `emails` suppresses up to 1,000 addresses as one decision and\nanswers what it did (`200`): how many it suppressed, how many were suppressed already, and\neach entry that is not an address. Either way the reason is `manual`, and every live\nenrollment of an address suppressed now stops in the same transaction.", "operationId": "suppressions.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "A list": { "summary": "Suppress a list of addresses in one decision", "value": { "emails": [ "no-mail@example.com", "Former.Customer@example.org", "not an address" ] } }, "One address": { "summary": "Suppress one address", "value": { "email": "no-mail@example.com" } } }, "schema": { "$ref": "#/components/schemas/SuppressionForm" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressedAddresses" } } }, "description": "For `emails`: what the request did." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionObject" } } }, "description": "For `email`: the suppression." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "For `email`: the address is suppressed already (`conflict`)." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid: neither or both of `email` and `emails`, an `email` that is not an address, more than 1,000 `emails`, or a reason other than `manual`." } }, "security": [ { "bearer": [] } ], "summary": "Suppress an address, or a list of them: no mail of the workspace reaches them any more.", "tags": [ "Audience" ], "x-norbelys-overloads": [ { "request": { "$ref": "#/components/schemas/CreateSuppression" }, "response": { "$ref": "#/components/schemas/SuppressionObject" } }, { "request": { "$ref": "#/components/schemas/CreateSuppressions" }, "response": { "$ref": "#/components/schemas/SuppressedAddresses" } } ] } }, "/v1/suppressions/{id}": { "delete": { "description": "The removal is audited. Suppressions that evidence created are read-only.", "operationId": "suppressions.delete", "parameters": [ { "description": "The suppression id (`sup_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Suppression" } } ], "responses": { "204": { "description": "The suppression is removed." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such suppression in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The suppression's reason is not `manual` (`invalid_state`)." } }, "security": [ { "bearer": [] } ], "summary": "Remove a manual suppression.", "tags": [ "Audience" ] }, "get": { "operationId": "suppressions.retrieve", "parameters": [ { "description": "The suppression id (`sup_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Suppression" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionObject" } } }, "description": "The suppression." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `people:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such suppression in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a suppression.", "tags": [ "Audience" ] } }, "/v1/threads": { "get": { "description": "`sort=last_activity_at` orders them by their latest message, sent or received, instead: the\ninbox's order. A thread moves when a message arrives, so it can move between pages while\nthey are read.", "operationId": "threads.list", "parameters": [ { "description": "Threads per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`id` (default, the creation order) or `last_activity_at` (the latest message, sent or received); ties are ordered by id.", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Threads with this person.", "in": "query", "name": "person_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Person" } }, { "description": "Threads of this connection's identities.", "in": "query", "name": "connection_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_Connection" } }, { "description": "Threads in this status (a snooze that ended is `open`).", "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/ThreadStatus" } }, { "description": "Threads with an inbound message of this classification.", "in": "query", "name": "classification", "required": false, "schema": { "$ref": "#/components/schemas/InboundClassification" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ThreadObject" } } }, "description": "A page of threads." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's threads, newest first by default.", "tags": [ "Inbox" ] } }, "/v1/threads/{id}": { "get": { "operationId": "threads.retrieve", "parameters": [ { "description": "The thread id (`thr_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Thread" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadObject" } } }, "description": "The thread.", "headers": { "ETag": { "description": "The thread's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such thread in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a thread with its latest 50 messages, outbound and inbound, oldest first.", "tags": [ "Inbox" ] }, "patch": { "operationId": "threads.update", "parameters": [ { "description": "The thread id (`thr_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Thread" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "snoozed_until": "2026-10-09T08:00:00Z", "status": "snoozed" }, "schema": { "$ref": "#/components/schemas/UpdateThread" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadObject" } } }, "description": "The thread.", "headers": { "ETag": { "description": "The thread's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `inbox:write`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such thread in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid: `snoozed` without a future `snoozed_until`, or `snoozed_until` without `snoozed`." } }, "security": [ { "bearer": [] } ], "summary": "Change a thread's status (open, snooze or archive it) or mark it read.", "tags": [ "Inbox" ] } }, "/v1/webhook_deliveries": { "get": { "description": "The order is by event, then by delivery.", "operationId": "webhook_deliveries.list", "parameters": [ { "description": "Deliveries per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only deliveries to this endpoint.", "in": "query", "name": "webhook_endpoint_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } }, { "description": "Only deliveries of this event.", "in": "query", "name": "event_id", "required": false, "schema": { "$ref": "#/components/schemas/Id_OutboxEvent" } }, { "description": "Only deliveries in this state.", "in": "query", "name": "state", "required": false, "schema": { "$ref": "#/components/schemas/WebhookDeliveryState" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_DeliveryObject" } } }, "description": "A page of deliveries." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's webhook deliveries, newest events first by default.", "tags": [ "Automation" ] } }, "/v1/webhook_deliveries/{id}": { "get": { "operationId": "webhook_deliveries.retrieve", "parameters": [ { "description": "The delivery id (`whd_…`), also the `webhook-id` header.", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookDelivery" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryObject" } } }, "description": "The delivery." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such delivery in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a webhook delivery with its latest attempt.", "tags": [ "Automation" ] } }, "/v1/webhook_deliveries/{id}/retry": { "post": { "description": "A pending delivery's next attempt is brought forward; a finished one becomes pending again.\nThere is never a second run beside the automatic one.", "operationId": "webhook_deliveries.retry", "parameters": [ { "description": "The delivery id (`whd_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookDelivery" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryObject" } } }, "description": "The delivery, pending with its next attempt now." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such delivery in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Its endpoint is disabled (`invalid_state`); enable it first." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Its event is older than the replay window." } }, "security": [ { "bearer": [] } ], "summary": "Retry a webhook delivery now.", "tags": [ "Automation" ] } }, "/v1/webhook_endpoints": { "get": { "operationId": "webhook_endpoints.list", "parameters": [ { "description": "Endpoints per page, 1 to 100 (default 20).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "The `next_cursor` of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "`desc` (default) or `asc`.", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListOrder" } }, { "description": "`total_count` adds an exact count up to 10,000.", "in": "query", "name": "include", "required": false, "schema": { "$ref": "#/components/schemas/ListInclude" } }, { "description": "Only enabled, or only disabled, endpoints.", "in": "query", "name": "enabled", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_EndpointObject" } } }, "description": "A page of endpoints." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The cursor is not valid for this request." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "A parameter is invalid." } }, "security": [ { "bearer": [] } ], "summary": "List the workspace's webhook endpoints, newest first by default.", "tags": [ "Automation" ] }, "post": { "operationId": "webhook_endpoints.create", "parameters": [ { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "event_types": [ "message.sent", "message.failed" ], "url": "https://example.com/hooks/norbelys" }, "schema": { "$ref": "#/components/schemas/CreateEndpoint" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointObject" } } }, "description": "The endpoint, with its secret shown once.", "headers": { "ETag": { "description": "The endpoint's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Create a webhook endpoint. Its signing secret (`whsec_…`) is in this response only.", "tags": [ "Automation" ] } }, "/v1/webhook_endpoints/{id}": { "delete": { "operationId": "webhook_endpoints.delete", "parameters": [ { "description": "The endpoint id (`whe_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } } ], "responses": { "204": { "description": "The endpoint is deleted." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such endpoint in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Delete a webhook endpoint and its deliveries.", "tags": [ "Automation" ] }, "get": { "operationId": "webhook_endpoints.retrieve", "parameters": [ { "description": "The endpoint id (`whe_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointObject" } } }, "description": "The endpoint.", "headers": { "ETag": { "description": "The endpoint's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such endpoint in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a webhook endpoint (without its secret).", "tags": [ "Automation" ] }, "patch": { "operationId": "webhook_endpoints.update", "parameters": [ { "description": "The endpoint id (`whe_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } }, { "description": "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.", "example": "\"1790000000000000\"", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": false }, "schema": { "$ref": "#/components/schemas/UpdateEndpoint" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointObject" } } }, "description": "The endpoint.", "headers": { "ETag": { "description": "The endpoint's new `version`, quoted.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is not JSON, or `If-Match` is malformed (`invalid_request`)." }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such endpoint in this workspace." }, "412": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`If-Match` names a version that is no longer current (`precondition_failed`); nothing changed." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Update a webhook endpoint: its URL, its event types, or whether it is enabled.", "tags": [ "Automation" ] } }, "/v1/webhook_endpoints/{id}/replay": { "post": { "description": "Every delivery of its events created at or after `since` becomes pending with its next attempt\nnow. A disabled endpoint must be enabled first.", "operationId": "webhook_endpoints.replay", "parameters": [ { "description": "The endpoint id (`whe_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "since": "2026-10-01T00:00:00Z" }, "schema": { "$ref": "#/components/schemas/ReplayEndpoint" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointObject" } } }, "description": "The endpoint; its deliveries are reopened.", "headers": { "ETag": { "description": "The endpoint's `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such endpoint in this workspace." }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The endpoint is disabled (`invalid_state`); enable it first." }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "`since` is older than the replay window, or the body is invalid." } }, "security": [ { "bearer": [] } ], "summary": "Replay an endpoint's deliveries.", "tags": [ "Automation" ] } }, "/v1/webhook_endpoints/{id}/rotate_secret": { "post": { "description": "The new secret is in this response only; the old one keeps signing for 24 hours, so every\nattempt carries both signatures meanwhile.", "operationId": "webhook_endpoints.rotate_secret", "parameters": [ { "description": "The endpoint id (`whe_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_WebhookEndpoint" } }, { "description": "A stable key for this logical request; reuse it when retrying.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointObject" } } }, "description": "The endpoint, with its new secret shown once.", "headers": { "ETag": { "description": "The endpoint's new `version`, quoted.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `automation:manage`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such endpoint in this workspace." } }, "security": [ { "bearer": [] } ], "summary": "Rotate an endpoint's signing secret.", "tags": [ "Automation" ] } }, "/v1/workspaces/{id}": { "get": { "description": "Only the credential's own workspace exists for it; any other id is not found.", "operationId": "workspaces.retrieve", "parameters": [ { "description": "The workspace id (`ws_…`).", "in": "path", "name": "id", "required": true, "schema": { "$ref": "#/components/schemas/Id_Workspace" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceObject" } } }, "description": "The workspace.", "headers": { "ETag": { "description": "The workspace's version, for `If-Match`.", "schema": { "type": "string" } } } }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No valid credential." }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "The credential lacks `workspace:read`." }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "No such workspace for this credential." } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a workspace.", "tags": [ "Workspace" ] } } } }