Nitrosend API
v1.1.6https://api.nitrosend.comProductionhttp://localhost:8000Local developmentMulti-channel marketing automation API. Send email campaigns, build automation flows, manage contacts and segments, track events, and configure your Brand Kit — all via a single REST API.
Authentication
All /v1/my/* endpoints require authentication via Bearer token.
Accepted token types:
- API Key —
Authorization: Bearer nskey_live_... - JWT —
Authorization: Bearer <jwt>(obtained fromPOST /v1/login) - Shopify ID token — supplied by App Bridge for an installed embedded app
- Management credential —
Authorization: Bearer nsmc_live_..., pinned to one managed account and brand under the existingoperator_v1policy. Domain receiving setup and dashboard webhooks usedomain.read/manageandintegration.read/managerespectively. Inbox capability, domain ownership, consent/payment eligibility and live revocation still apply. Management credentials cannot mint API keys, provision sibling accounts, buy capacity or manage billing; they can read a client's plan, plan list and features (billing.plan_purchase). MCP event subscriptions remain unavailable to delegated operators.
An agency's owners and admins work in a client account it manages with
their own JWT and X-Account-ID under the same operator_v1 policy. The
one billing action that policy allows is buying the client's first plan
by card while the account is in Setup mode (POST /v1/my/subscription);
plan changes, checkout, settings, cancel, coupons, payment methods and
invoices stay with the client's owner and admins.
Pagination
Paginated endpoints return these headers:
X-Total-Count— total recordsX-Total-Pages— total pagesX-Page-Number— current pageX-Next-Page— next page (omitted on last page)X-Prev-Page— previous page (omitted on first page)
Use page and limit (or per) query params to control pagination.
Maximum limit is 100, default is 30.
Error Responses
All errors return a consistent JSON shape:
{
"code": 422,
"message": "Description of error",
"error": true,
"validation_errors": { "field": ["error message"] }
}The validation_errors key is only present on 422 responses.
A signed-in user who has no account is given one on their first
authenticated request. If their email domain is not eligible for signup,
no account is created and the request returns 403 with
"message": "Email domain is not eligible for signup".
Authentication
BearerAuthhttpAuthentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Scheme: bearer
PartnerProvisioningCredentialhttpManager-account provisioning credential revealed once at issuance.
Scheme: bearer (nspk_live)
ManagementCredentialhttpOne-time-revealed operator_v1 credential pinned to one active management grant and Brand.
Scheme: bearer (nsmc_live)
Auth
Login, logout, and registration
Begin email-verified signup
Body
userobjectrequiredParameters
X-Nitrosend-Device-TypestringcomputerphonetabletheaderBounded client-declared signup measurement; never authentication or account authority. OAuth preserves it through the existing signed attribution context.
X-Nitrosend-In-App-BrowserstringInstagramFacebookTikTokLinkedInXGoogle appthis appheaderBounded client-declared embedded browser measurement. Omitted or unknown is unclassified, not proof of a standalone browser.
Response
Verification required. No account, membership, API key or session has been created. The same response covers existing addresses; sign in if already registered.
Validation failed
Signup acquisition or mail capacity reached. Keep existing credentials and retry after the stated delay; rotating IPs or email domains does not bypass these limits.
Signup paused or mail could not be queued. Retry later.
Request an email verification link
A link lasts 30 minutes. Resending does not invalidate an unexpired link. Limited to three requests per address per UTC day, at least one minute apart, and a global daily mail budget. Unknown and established addresses get the same response and limits.
Body
emailstring<email>requiredResponse
If eligible, verification mail is queued. No credential is returned.
Signup acquisition or mail capacity reached. Keep existing credentials and retry after the stated delay; rotating IPs or email domains does not bypass these limits.
Mail could not be queued. Retry later.
Prove email ownership and complete signup
Explicitly POST the one-use token from the verification email and choose the final password. The final password replaces the signup password. Opening the link alone does not consume proof. No CAPTCHA or browser is required. After proof commits, a temporary activation failure can be retried through /v1/signup/activate without another email. A token for an established user's email change needs no password, returns email_verified without a JWT, and leaves their password and session unchanged.
Body
tokenstring<password>requiredwrite onlypasswordstring<password>write onlyRequired to complete a new password signup.
Response
Signup complete, or an established email change confirmed.
Validation failed
Signup acquisition or mail capacity reached. Keep existing credentials and retry after the stated delay; rotating IPs or email domains does not bypass these limits.
Proof may already be saved. Retry activation with email and final password.
Resume an already verified signup
Requires email ownership already proved and the final password. Returns the existing account/session if activation already succeeded. Does not create another account. Use this after a lost verification response, capacity deferral, or a client failure creating or saving its API key.
Body
emailstring<email>requiredpasswordstring<password>requiredwrite onlyResponse
Active session
Validation failed
Signup acquisition or mail capacity reached. Keep existing credentials and retry after the stated delay; rotating IPs or email domains does not bypass these limits.
Activation could not finish. Retry with the same email and final password.
Sign in and receive a JWT
Sign out and revoke JWT
Response
Signed out
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get OAuth popup context
Returns the account-selection and subscription context used by the
/oauth/connect popup. This endpoint accepts the normal Bearer JWT
and, for popup resume flows, the authenticated browser session cookie
established by Devise/OmniAuth.
Parameters
client_idstringqueryOAuth application ID, used to name the connection being authorized.
Response
Popup context
Not authenticated
The user has no account yet and their email domain is not eligible for signup, so none is created.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Subscribe the selected OAuth popup account
Finalizes plan selection for the /oauth/connect popup before the
browser returns to the Doorkeeper consent screen. This endpoint accepts
the normal Bearer JWT and, for popup resume flows, the authenticated
browser session cookie established by Devise/OmniAuth.
Body
plan_idintegerrequiredaccount_idinteger | nullstripe_tokenstring | nullResponse
Popup can continue to consent
Not authenticated
The user cannot manage the selected account, the account must buy through another billing provider (billing_route says which), or the user has no account yet and their email domain is not eligible for signup.
Account or plan selection failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a CSRF-safe OAuth provider launch URL
Mints a short-lived launch URL for Google or GitHub sign-in. The
frontend follows the returned API-origin launch page, which renders the
real POST form to /auth/:provider with a valid Rails authenticity
token. This preserves OmniAuth's POST-only request phase and CSRF
protection for both the app popup flow and the /oauth/connect agent
popup flow.
Body
providerstringgoogle_oauth2githubrequiredauth_intentstringappagentappauth_stepstringloginsignuploginresume_urlstring<uri> | nullRequired when auth_intent=agent; must point to the frontend /oauth/connect route.
invite_tokenstring | nullreferral_codestring | nullrewardful_referral_idstring | nullattribution_contextFirstTouchAttributionContextOptional first-touch attribution captured by the client for a new-account signup. Send URLs without query strings. UTM values have control characters removed and surrounding whitespace stripped, and are capped at 100 characters server-side. Click identifiers are accepted only as strings: surrounding whitespace is stripped, then the whole value must be 1-255 ASCII letters, digits, underscores, periods or hyphens; an invalid or oversized identifier is omitted, never truncated, without rejecting the signup. Values are persisted only for a genuinely new account and never overwrite an earlier first touch.
signup_intentSignupIntent | nullagencyOptional. agency marks a signup that came from the agencies page; a new account created with it becomes a partner (Affiliates tab, client management, a personal Rewardful campaign) unless the signup is held for review. Any other value is ignored and the signup proceeds normally.
Parameters
X-Nitrosend-Device-TypestringcomputerphonetabletheaderBounded client-declared signup measurement; never authentication or account authority. OAuth preserves it through the existing signed attribution context.
X-Nitrosend-In-App-BrowserstringInstagramFacebookTikTokLinkedInXGoogle appthis appheaderBounded client-declared embedded browser measurement. Omitted or unknown is unclassified, not proof of a standalone browser.
Response
Launch URL created
Invalid provider or resume URL
Sign in with a one-time link
Body
tokenstringrequiredResponse
A session token and the account and brand to open
Not a link we issued
Expired or already used
Send a fresh link to the owner of an expired one
Always answers 202, and sends only to the account's own address, so it says nothing about whether the token named an account.
Body
tokenstringrequiredResponse
Accepted
User
Current user profile
Get current user profile
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update current user profile
Body
first_namestringlast_namestringemailstring | Array<string>mobilestringtime_zonestring | nullResponse
Updated user
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get current impersonation status
Response
Current impersonation state
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Revoke the active impersonation session
Response
Impersonation session revoked
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Account
Account settings and configuration
Get account details
Response
Account with billing. Brands are listed by GET /v1/my/brands.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update account settings
Body
namestringavatarstringSigned blob ID
bannerstringSigned blob ID
Response
Updated account
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List accessible accounts (paginated)
Parameters
pageinteger1queryperinteger<= 100100queryResponse
Accessible accounts
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get the current account's pending or active management grant
Only the canonical owner of the selected managed account may use this endpoint.
Response
Current management grant
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Reconcile a consented, paid managed-account grant
This endpoint cannot record owner consent or bypass paid activation.
Body
management_grant_idintegerrequiredExact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.
Response
Active management grant
Bad request
Not authorized
Resource not found
The grant cannot transition from its current state
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Revoke an exact pending or active management grant
Revocation takes effect on the next REST or MCP request and is idempotent for the exact grant.
Body
management_grant_idintegerrequiredExact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.
Response
Revoked management grant
Bad request
Not authorized
Resource not found
The grant cannot transition from its current state
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get team metadata for the current account
Response
Team metadata
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
How far one send to an audience gets on the current plan
Read-only. Reports the recipients per day at the account's sending standing and the emails left this month on the current plan, whether they cover a full send to the audience, and the cheapest listed plan whose first month would. The numbers come from the plan catalogue and this month's usage; the summary sentence is the one every surface shows. Silent (no summary, no recommendation) when the current plan covers the audience.
Parameters
audienceinteger>= 1requiredqueryNumber of recipients of one full send
Response
Reach on the current plan and the recommended plan
audience is not a positive whole number (error_code audience_invalid)
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List account memberships (paginated)
Parameters
pageinteger1queryperinteger<= 100100queryResponse
Memberships
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Remove a membership
Parameters
idintegerrequiredpathResponse
Removed membership
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a membership role
Body
rolestringmemberadminParameters
idintegerrequiredpathResponse
Updated membership
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List account invites (paginated)
Parameters
pageinteger1queryperinteger<= 100100queryResponse
Invites
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create an account invite
Body
emailstring<email>requiredrolestringmemberadminResponse
Created invite
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Revoke an invite
Parameters
idintegerrequiredpathResponse
Revoked invite
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Accept an invite token
Parameters
idstringrequiredpathResponse
Accepted invite
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Affiliate Center
Entitled affiliate link, standing, and lifetime performance
Get the current account's Affiliate Center
Session/JWT only. API keys are rejected. For an entitled account that is not linked locally, the first read starts one background reconciliation. That reconciliation links an existing Rewardful affiliate by the account owner's email or creates one when absent.
Response
Affiliate Center payload or temporary setup state
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Reconcile the current account's affiliate immediately
Session/JWT-only repair path. This is idempotent and uses the same existing-or-create behavior as background reconciliation.
Body
first_namestringlast_namestringResponse
Existing or already-linked affiliate
Affiliate identity linked to the account
Not authorized
Resource not found
Validation failed
Upstream service unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Managed Clients
Explicitly enabled client provisioning, consent, and portfolio operations
List the selected manager account's client portfolio
Parameters
pageinteger1queryperinteger<= 10025queryqstringquerystatusManagedAccountLifecycleStatusFilterqueryUse needs_setup to group preparing, awaiting owner, payment required, and payment issue rows.
sortstringcreated_atnameowner_emailstatuscreated_atquerydirectionstringascdescdescqueryResponse
Bounded managed-client portfolio
Not authorized
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Provision a paid-required, client-owned account
Body
managed_accountobjectrequiredParameters
Idempotency-KeystringrequiredheaderExact-request idempotency key; changed normalized input conflicts.
Response
Exact idempotent replay
Client provisioned in preparing state; no owner invitation has been sent
Not authorized
Request conflicts with durable lifecycle or idempotency state
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get one managed-client portfolio row
Parameters
idintegerrequiredpathResponse
Managed-client portfolio row
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Invalidate the prior invitation and queue a bounded replacement for owner-only delivery
Parameters
idintegerrequiredpathResponse
Updated portfolio row; no invitation capability is returned
Not authorized
Request conflicts with durable lifecycle or idempotency state
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Queue the first bounded owner invitation after client setup is ready
Parameters
idintegerrequiredpathResponse
Updated portfolio row; no invitation capability is returned
Not authorized
Request conflicts with durable lifecycle or idempotency state
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Queue a cooldown-bound payment reminder to the owner
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
End the selected manager's relationship with the client
Parameters
idintegerrequiredpathResponse
Ended managed-client relationship
Not authorized
Request conflicts with durable lifecycle or idempotency state
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List non-secret provisioning credential metadata
Response
Provisioning credential metadata
Not authorized
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Issue a provisioning credential and reveal its secret once
Body
credentialobjectrequiredResponse
One-time credential result
Not authorized
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Revoke one manager-bound provisioning credential
Parameters
idintegerrequiredpathResponse
Revoked credential metadata
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Inspect a bounded owner consent capability
Body
claimobjectrequiredResponse
Bounded claim projection
One-time capability is invalid, expired, rotated, or consumed
Record one-time consent for the exact authenticated owner
Body
claimobjectrequiredResponse
Consent recorded. A client on Setup mode is active at once (the agency keeps building) with payment_required true, since live email waits for a plan; a client with a paid plan already active is active with payment_required false; otherwise status remains payment_required until paid activation
Not authorized
One-time capability is invalid, expired, rotated, or consumed
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Partner
Provisioning-credential authenticated managed-client operations
List managed clients using a manager-bound credential
Response
Managed-client portfolio
Not authenticated
Not authorized
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Provision a paid-required client-owned account
Body
managed_accountobjectrequiredParameters
Idempotency-KeystringrequiredheaderExact-request idempotency key; changed normalized input conflicts.
Response
Exact idempotent replay
Client provisioned in preparing state; no owner invitation has been sent
Not authenticated
Not authorized
Request conflicts with durable lifecycle or idempotency state
Validation failed
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Get one manager-scoped portfolio row
Parameters
idintegerrequiredpathResponse
Managed-client portfolio row
Not authenticated
Not authorized
Resource not found
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Invalidate the prior invitation and queue a bounded replacement for owner-only delivery
Parameters
idintegerrequiredpathResponse
Updated portfolio row; no invitation capability is returned
Not authenticated
Not authorized
Request conflicts with durable lifecycle or idempotency state
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Queue the first bounded owner invitation after client setup is ready
Parameters
idintegerrequiredpathResponse
Updated portfolio row; no invitation capability is returned
Not authenticated
Not authorized
Request conflicts with durable lifecycle or idempotency state
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
List non-secret agent credential metadata for one managed client
Parameters
provisioning_idintegerrequiredpathManager-scoped provisioning row id.
Response
Agent credential metadata; plaintext secrets are never listed
Not authenticated
Not authorized
Resource not found
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Issue one grant- and Brand-pinned agent credential
Body
credentialobjectrequiredParameters
provisioning_idintegerrequiredpathManager-scoped provisioning row id.
Response
One-time credential result; the secret cannot be recovered
Not authenticated
Not authorized
Resource not found
Request conflicts with durable lifecycle or idempotency state
Validation failed
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Revoke one agent credential immediately
Parameters
provisioning_idintegerrequiredpathManager-scoped provisioning row id.
idintegerrequiredpathResponse
Revoked credential metadata
Not authenticated
Not authorized
Resource not found
Authorization
PartnerProvisioningCredentialhttp (bearer)Manager-account provisioning credential revealed once at issuance.
Billing
Subscription billing and checkout
Download an account invoice
Returns the original Stripe invoice PDF for an invoice in the current account. Requires account owner or admin access. The response is inline application/pdf with Cache-Control private, no-store. The existing trailing-slash and .pdf URL forms return the same document.
Parameters
idintegerrequiredpathResponse
Original invoice PDF
Not authenticated
Not authorized
Invoice not found in the current account, ownership cannot be verified, or no Stripe PDF is available
The invoice document could not be retrieved
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Ask the Nitrosend team about Enterprise
Sends the signed-in member's Enterprise request, with the account's context, to the Nitrosend team. Each member can send one request per UTC day; a repeat answers with their first request (replayed true). Agency (delegated) sessions are refused.
Body
monthly_emailsinteger | string | nullEmails a month they expect to send, from 0 to 1,000,000,000, as a whole number or a string of up to 10 digits.
needsArray<string> | nullvolume_pricingdedicated_ipseats_or_domainssecurity_reviewinvoicingmigrationmessagestring | nullResponse
This member already sent a request today; the receipt is for that request
Request received
Not authenticated
Not authorized
A field has the wrong shape or is out of range (error_code enterprise_request_invalid, with validation_errors per field).
The request could not be sent to the team, so it was not kept (error_code enterprise_request_unrecorded); email contact@nitrosend.com instead.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read the current subscription
Owners and admins read the full subscription; other members are
refused. An agency operator working in a client account it manages
(delegated access holding billing.plan_purchase) reads the delegated
projection instead: the plan, its status and the billing route, which
is what buying the client's first plan from Setup mode needs, with no
payment, invoice, discount, spend cap or renewal details. A management
credential reads the same projection.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a subscription
Buys a paid base plan by card (stripe_token), always as a new
subscription. Owners and admins can buy any plan the account is
offered, with an optional coupon.
An agency operator working in a client account it manages (delegated
access holding billing.plan_purchase) can buy only the client's
first plan: Starter or above, by card, while the account is in Setup
mode, sending plan_id and stripe_token and nothing else. Any other
field, a coupon included, is refused before Stripe is called. The
subscription stays on the client account, the card is saved to the
account owner's Stripe customer and invoices go to the owner's email.
Only a person signed in to Nitrosend can buy this way: a management
credential cannot. The response is the delegated subscription
projection.
Body
plan_idintegerrequiredstripe_tokenstring | nullStripe card token for paid-plan creation.
coupon_codestring | nullCustomer-entered Stripe promotion code or coupon ID. Refused on an agency operator's purchase for a client account.
Response
Subscription created
Not allowed for this caller: billing is managed by another provider (error_code manage_on_shopify or billing_provider_unavailable), the caller is not an owner or admin, or an agency purchase is outside its limits (error_code delegated_purchase_refused, with a message written for the customer: the account is not in Setup mode, the plan is not Starter or above, the request sent more than plan_id and stripe_token or no card token, or the caller is an agent credential).
The plan is not available to this account, including Free for an agency or a client account an agency created.
Another upgrade for this account is still being processed, or the account already pays for a plan through Stripe (error_code plan_checkout_pending, with a message written for the customer).
Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer). When the customer's bank asked to verify the payment (3D Secure) and the caller is the account's own owner or admin (not an agency operator, who can't open hosted checkout), the error also has recovery_action (StartHostedCheckoutAction) naming the plan; start POST /v1/my/subscription/checkout for that plan with new_subscription and the same coupon_code to finish on Stripe's hosted checkout, which runs the bank's check.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Cancel the current paid plan at its period end
Schedules the current paid plan to end at its period end, using the account's Free plan as the cancellation marker. An agency, or a client account an agency created, is never sold Free: when its cancelled plan ends it returns to its Setup subscription. The Setup subscription itself cannot be cancelled.
Response
Cancellation scheduled
Billing for this account is managed by another provider (error_code manage_on_shopify or billing_provider_unavailable)
There is no paid plan this account can cancel here.
The account is on Setup mode, which has no subscription to cancel (error_code setup_mode_not_cancellable, message "Setup mode has no subscription to cancel.").
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Change the current subscription plan
Changes an existing plan. Free is not available to an agency or a client account an agency created. A Setup subscription is never changed: leave Setup by buying a plan with POST /v1/my/subscription or /v1/my/subscription/checkout, which create a new subscription.
Body
plan_idintegerrequiredcoupon_codestring | nullCustomer-entered Stripe promotion code or coupon ID.
Response
Subscription updated
The change cannot be applied, including any change from Setup mode (message "Choose a plan to leave Setup mode.").
The plan is not available to this account, including Free for an agency or a client account an agency created.
Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer).
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start a subscription checkout
Creates or replays one account-scoped plan purchase through the authoritative billing provider. A Stripe-backed active subscription is changed in place within the same product. Optional account features have independent recurring subscriptions and never replace the base plan. Omitted product_key selects the base plan. Use an available product key returned for this account. A feature is saleable only through a rail that explicitly supports it. Shopify-managed accounts receive a Shopify-hosted approval URL and never receive a Stripe checkout URL.
Body
plan_idintegerrequiredproduct_keystringbase_planbrand_capacitydomain_capacityseat_capacityfooter_removalbase_planquantityinteger[1, 10000]1Units for a quantity-based offer returned by features. Other offers require one. Bound to the idempotency key.
idempotency_keystringOptional body form of Idempotency-Key for compatibility.
new_subscriptionbooleanfalseThe caller is buying this product's first paid plan, such as a bank check the card form couldn't run (StartHostedCheckoutAction). A purchase that would change or cancel the account's current plan is refused with 409 instead of made, and a hosted checkout left open by an earlier attempt is closed first.
coupon_codestringA coupon for the base plan's hosted checkout, applied as the card form would have applied it. Needs new_subscription; an invalid coupon, or one on any other purchase, is refused with 422. Bound to the idempotency key exactly as sent.
Parameters
Idempotency-KeystringheaderOptional stable retry key. The server also reuses an open same-plan checkout.
Response
Subscription changed without external approval
Provider-hosted checkout created
Billing provider is not ready for checkout, or an account feature needs an active paid base plan first (error_code base_plan_required; on Setup mode every feature waits for a paid base plan)
Requested plan is not available, including Free for an agency or a client account an agency created
Another checkout is pending, the idempotency key conflicts, or (with new_subscription) the account already has another paid plan (error_code plan_checkout_pending)
Shopify rejected the requested billing terms, or the coupon is invalid or can't apply (validation_errors.coupon_code)
The billing provider could not be reached
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Reconcile and read a plan purchase
Reads the requested plan while approval is pending. Stripe and Shopify are read back before the local state is returned. Omit purchase_id to inspect the latest pending checkout or current subscription for that product.
Parameters
product_keystringbase_planbase_planquerypurchase_idintegerqueryResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read the current prepaid funding projection and available instruments
Response
Current prepaid funding status
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start an add-funds purchase with an optional hosted instrument
Creates or replays one local funding purchase. Current public instruments return a provider-hosted approval URL. No request-side credential field is exposed by this endpoint.
Body
amount_centsinteger>= 1requiredInteger service value in minor currency units.
currencystringinstrumentstringstripe_checkoutshopify_one_timeOptional hosted funding instrument. Omit to use the account default.
paid_action_intent_idstring | nullOptional opaque continuation bound to this funding purchase.
Parameters
Idempotency-KeystringrequiredheaderResponse
Existing idempotent funding purchase
Funding purchase created
Idempotency key was used for different funding input
Amount or selected funding instrument is unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read an account-scoped funding purchase
Parameters
idstringrequiredpathLocal purchase ID or opaque Stripe Checkout Session ID
Response
Funding purchase status
Funding purchase not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Preview a promotion code or coupon for a subscription plan
Validates a customer-entered Stripe promotion code or coupon ID against
a paid plan and returns display totals for the checkout summary. The
final subscription create/change request must still send coupon_code;
preview data is not trusted as payment input.
Body
plan_idintegerrequiredcoupon_codestringrequiredCustomer-entered Stripe promotion code or coupon ID.
Response
Coupon preview
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read the selected account's recurring subscription cards
Account administrator required. Reads actual provider subscription defaults; never returns payer profile details or changes a shared customer default.
Response
Masked cards by subscription, product_key and plan_name
Not authorized
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Replace the card on this account's current plan and paid features
Account administrator required. Provider ownership is checked before changing any term. Success requires independent readback of every term. This does not pay outstanding invoices or change another account's subscriptions.
Body
stripe_tokenstringrequiredwrite onlyResponse
Confirmed masked cards by account subscription
Not authorized
Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer).
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Refuse removal while current recurring terms require payment
Response
No recurring account payment method exists
Not authorized
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Open the provider-hosted payment page for an owned unpaid invoice
Account administrator required. Performs fresh provider ownership and open-status checks. Payment and authentication happen on Stripe. Access resumes through the existing paid invoice receipt path.
Parameters
idintegerrequiredpathResponse
Ownership-verified HTTPS Stripe invoice payment URL
Not authorized
Invoice does not belong to this account or cannot be paid
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create or exactly replay a resumable paid operation
Persists encrypted, operation-owned continuation state. The intent is not spend authority and never executes the operation automatically.
Body
adapter_keystringrequiredadapter_versionstringrequiredoperation_idempotency_keystringrequiredstate_payloadobjectrequiredAdapter-owned state, validated and encrypted before persistence.
Response
Exact idempotent replay
Continuation created
Operation key reused with different continuation state
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Restore and re-quote a paid operation
Parameters
idstringrequiredpathOpaque paid-operation continuation identifier.
Response
Actor-scoped continuation with current terms
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Cancel and scrub a paid-operation continuation
Parameters
idstringrequiredpathOpaque paid-operation continuation identifier.
Response
Cancelled continuation
Resource not found
Terminal continuation cannot be cancelled
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Mark a successfully executed paid operation consumed
Parameters
idstringrequiredpathOpaque paid-operation continuation identifier.
Response
Consumed continuation
Resource not found
Continuation is not ready to consume
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delivery
Read-only plan/cohort sending allowance and pacing state
Inspect the email sending allowance and pacing
Returns a read-only projection of the persisted delivery controls for the selected Brand. This endpoint does not authorize or reserve a send; every send still passes through the canonical admission authority. Pacing describes when admitted work can dispatch and is not itself an admission decision.
Response
Current email sender-capacity and pacing projection
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Email Validation
Explicit prepaid email validation quotes and operations
Quote explicit prepaid email validation
Classifies one exact current-Brand audience, applies current cached and eligibility evidence, and returns the maximum prepaid charge. It does not hold funds, call a provider, create an operation, or mutate Contacts. Validation has no plan-included allowance.
Body
lead_idsArray<integer>Explicit Lead selection in the current Brand. Does not create marketing Contacts or require a discovery search.
contact_channel_idsArray<integer>contact_idsArray<integer>list_idintegersegment_idintegerall_contactsbooleanAll email channels in the current Brand, subject to the 100000-candidate operation bound.
quote_digeststringPass the reviewed quote digest when creating an operation. A changed address set, eligibility or price returns 409 validation_quote_changed without holding funds. Omit only when intentionally authorizing the current audience at the current price.
Response
Non-mutating validation quote
Bad request
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
The brand's latest contact list verifications
Newest first, contact audiences only. Use the operation_id with the show endpoint for results and the sending choice.
Parameters
limitinteger[1, 20]5queryResponse
Latest verifications
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start or resume explicit prepaid email validation
Creates one durable operation and holds at most the quoted amount from direct prepaid funds. Reusing the same Idempotency-Key with the same audience returns the same operation; after funding, the same request resumes a needs_funding operation. A changed audience conflicts.
Body
lead_idsArray<integer>Explicit Lead selection in the current Brand. Does not create marketing Contacts or require a discovery search.
contact_channel_idsArray<integer>contact_idsArray<integer>list_idintegersegment_idintegerall_contactsbooleanAll email channels in the current Brand, subject to the 100000-candidate operation bound.
quote_digeststringPass the reviewed quote digest when creating an operation. A changed address set, eligibility or price returns 409 validation_quote_changed without holding funds. Omit only when intentionally authorizing the current audience at the current price.
Parameters
Idempotency-KeystringrequiredheaderExact-request idempotency key; changed normalized input conflicts.
Response
Durable validation operation accepted or replayed
Bad request
Not authenticated
Resource not found
Request conflicts with durable lifecycle or idempotency state
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get an email validation operation
Parameters
idstringrequiredpathOpaque operation_id returned by the create endpoint.
Response
Current durable operation state
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Keep a finished run's unknown and catch-all addresses in sends
A finished list verification leaves unknown and catch-all addresses out of sends by default. This keeps sending to the ones this run left out. Addresses stopped for another reason (a bounce, an unsubscribe, an invalid result) stay stopped.
Parameters
idstringrequiredpathResponse
Updated operation state
Not authenticated
Resource not found
The run is still finishing or its addresses are still being left out (error_code validation_in_progress), or sending resumed automatically on the condition unconfirmed addresses stay out (error_code unconfirmed_include_blocked; contact support to include them).
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Leave a finished run's unknown and catch-all addresses out of sends
Applies the default to a run that predates it, or after its addresses were kept. Runs in the background; poll the operation until unconfirmed.pending is false.
Parameters
idstringrequiredpathResponse
Updated operation state
Not authenticated
Resource not found
The run is still finishing or its addresses are still being left out.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List per-candidate email validation results
Parameters
idstringrequiredpathOpaque operation_id returned by the create endpoint.
pageinteger1queryperinteger<= 10030queryResponse
Paginated operation items
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Contacts
Contact management
List contacts (paginated)
Parameters
pageinteger1querylimitinteger<= 10050querysearchstringqueryFull-text search across name, email, phone
filtersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupqueryCanonical structured audience filters from the registry exposed by
/v1/my/flows/spec and nitro://schema. search remains a separate
full-text lookup; filters are applied through the same fail-closed
validator used for segments.
list_idintegerqueryLegacy shortcut for a contact_list in [id] filter.
tagstringqueryLegacy shortcut for a contact_tag eq tag filter. Tags are stored
as an array of strings under data.tags. For richer tag targeting,
use canonical filters.
sortstringcreated_atemails_sentunique_opensclicksopen_rateclick_ratelast_opened_atlast_clicked_atratingqueryColumn to sort by. created_at orders by the contact's creation date;
the rest are the per-contact engagement rollup fields (see
Contact.engagement). Contacts with no rollup row always sort last.
Any unrecognised value falls back to the default newest-first order.
directionstringascdescdescquerySort direction. Only applies when sort is set.
Response
Paginated contacts
A read did not finish within the request's database time limit (error_code: query_timeout). Nothing was changed; retry after the Retry-After interval. Any GET can return this.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a contact
Body
first_namestringlast_namestringemailstring<email>Normalized to lowercase. Email is what identifies a contact in a brand: if a contact in this brand already has this email, that contact is updated (200) instead of duplicated, whatever phone is submitted. Creates/updates the email channel with opt_in.
phonestringE.164 format. Creates/updates the phone channel with opt_in. A phone is not an identity: several contacts in a brand may share one (a household, a reception line), so submitting a phone another contact holds never conflicts. With no email, the phone updates an existing contact only when exactly one contact in the brand holds it; when several do, the request is rejected (422, validation_errors.phone) and must include an email, or update a specific contact with PATCH /v1/my/contacts/{id}.
sourcestringcountry_codestringopt_inboolean | nullConsent for supplied email/phone channels. Omitted or null preserves existing subscription state; a new email keeps the collection default and a new phone needs opt-in. True explicitly opts in without removing suppression. False opts an existing channel out; a new channel starts without consent.
list_idsArray<integer>dataobjectCustom key-value data. The reserved key tags holds an
array of string labels used for segmentation, e.g.
{"tags": ["vip", "newsletter"]}.
Merge-on-resolve behavior (create path only): when the
submitted email (or, with no email, a phone held by exactly
one contact) resolves to an existing contact, data is merged into the contact's existing data
rather than replaced. Blank incoming values are ignored;
caller-supplied non-reserved keys overwrite their
counterparts; the reserved enrichment keys apollo, pdl,
attio, hubspot, stripe, shopify, and nitro are
preserved from the stored contact;
and tags from both sides are unioned. The update endpoint
(PATCH /v1/my/contacts/{id}) uses the same merge, except
that a supplied tags array replaces the tag set.
{
"tags": [
"vip",
"newsletter"
],
"plan": "pro"
}channels_attributesArray<object>Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Apply an action to selected contacts
Applies only to contacts in the current brand. Unsubscribe email stops that brand's marketing and retains the choice after contact deletion. SMS subscriptions and other brands are unchanged. Delete can target match (the contacts index's own filter params) instead of ids, and dry_run previews the count and wording. A match delete is confirmed with the preview's selection_digest and deletes exactly the contacts that preview counted; if they changed, it returns 422 selection_changed and deletes nothing. A delete selects at most 100,000 contacts (422 too_many). Deleting keeps unsubscribes, bounces and complaints. A delete of more than 100 contacts runs in the background (202) and emails the account owner when it's done. Contacts still in use, such as in email conversations or an email verification that is still running, are kept and counted in kept.
Body
action_typestringadd_to_listremove_from_listdeleteunsubscribe_emailrequiredidsArray<integer>Required unless match is sent. Send one of ids or match.
list_idintegerRequired for add_to_list and remove_from_list.
matchobjectDelete only. Selects the contacts GET /v1/my/contacts returns for the same params. {} selects every contact in the brand. Any other key is rejected with 422.
dry_runbooleanDelete only. Returns the count and confirmation wording without deleting.
selection_digeststringDelete with match only, and required there. The selection_digest from the dry run being confirmed.
Response
Action completed, or a delete dry run
Delete of more than 100 contacts queued to run in the background
Invalid action, invalid match or filters, or no matching contacts. For delete, code is also selection_required (a match confirm without a digest), selection_changed (the contacts changed since the preview) or too_many (over 100,000).
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a contact
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a contact
Parameters
idintegerrequiredpathResponse
Deleted contact
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a contact
Body
first_namestringlast_namestringemailstring<email>Adds or updates a channel for this address; it does not replace another email channel. Use channels_attributes with an existing id and value to correct that channel in place. An address owned by a different contact in the brand is rejected (422).
phonestringE.164 format. Several contacts in a brand may share a phone, so a phone another contact holds is accepted.
sourcestringcountry_codestringopt_inboolean | nullConsent for supplied email/phone channels. Omitted or null preserves existing subscription state. True explicitly opts in without removing suppression; false explicitly opts out.
list_idsArray<integer>dataobjectCustom key-value data. The reserved key tags holds an
array of string labels used for segmentation — e.g.
{"tags": ["vip", "newsletter"]}.
Custom keys merge into current data; omitted or blank
values preserve existing data. Existing reserved enrichment
namespaces, including apollo, pdl, attio, hubspot,
stripe, shopify, and derived nitro, are protected.
A supplied tags array replaces the editable tag set;
[] clears tags, and omitting tags preserves them.
Send only intended changes. For add/remove tag semantics across
many contacts, use the nitro_manage_audience MCP tool
with operation: "bulk_tag".
{
"tags": [
"vip",
"newsletter"
],
"plan": "pro"
}channels_attributesArray<object>Supply an existing channel id and value to correct its address in place. Email correction preserves current consent without a new opt-in event, retains old-address stops, applies new-address stops, and clears old-address verification and delivery-failure state.
Parameters
idintegerrequiredpathResponse
Updated contact
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Quote profile enrichment for Contacts or supplied Leads
Resolves already-current and same-Brand reusable profile evidence before provider work. This endpoint never calls a provider or reserves money. Profile enrichment is priced per successful outcome and has no plan-included allowance.
Body
Exactly one same-Brand selection. Existing identity and profile ownership are preserved.
contact_idsArray<integer>Response
Exact maximum-charge quote and work classification
Not authenticated
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Queue profile enrichment for Contacts or supplied Leads
Holds the quoted maximum, then queues bounded profile work. Current evidence is skipped without charge. Fresh same-Brand evidence and usable provider results each commit one outcome; no-match and failures void the hold. This operation does not verify, subscribe, suppress, or qualify an email channel.
Body
Exactly one same-Brand selection. Existing identity and profile ownership are preserved.
contact_idsArray<integer>Parameters
Idempotency-KeystringrequiredheaderResponse
Exact idempotent replay
Enrichment queued
Bad request
Not authenticated
Account funding changed before the enrichment hold was created
Idempotency-Key reused with different Contact IDs
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Unified activity timeline for a contact
Read-only, keyset-paginated feed merging the contact's lifecycle
events and email activities into one chronological stream (newest
first). Entries are normalised and whitelisted — raw rows are never
exposed. Page using the cursor returned as next_cursor.
Parameters
idintegerrequiredpathcursorstringqueryOpaque keyset cursor from a prior next_cursor.
limitinteger<= 10025queryResponse
A page of timeline entries, newest first
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Enrichment facts for a contact
Read-only enrichment facts resolved into display rows. Facts sourced from an integration you have connected are attributed with that integration's name; facts from other sources are returned unattributed.
Parameters
idintegerrequiredpathResponse
The contact's resolved enrichment rows
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List the field catalog for this account
Returns the structured field catalog: one row per known field for this account,
with key, category, type, label, promotion state, and async fill-rate.
Fields are lazily registered the first time a key is seen (import, API write,
or enrichment). Use PATCH /v1/my/contacts/fields/:id to update promoted
or label.
Response
Field catalog rows ordered by category and label
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a field catalog row (owner/admin only)
Updates the promoted flag and/or the human-readable label for a field
catalog row. Restricted to account owners and admins. The key, category,
and field_type of a row are immutable.
Body
promotedbooleanPin this field as a default column in the contacts grid.
labelstringOverride the human-readable label for this field.
Parameters
idintegerrequiredpathResponse
Updated field catalog row
Not authenticated
Not authorized
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Imports
Bulk CSV import jobs
Reserve a direct-upload blob
Creates an Active Storage direct-upload reservation and returns a
signed_id, presigned upload URL, and required upload headers. For CSV
imports, send purpose: import, PUT the file bytes to
direct_upload.url, then submit the returned signed_id to
POST /v1/my/imports. For image media assets, send purpose: image
or purpose: media_asset, PUT the image bytes to direct_upload.url,
then submit the returned signed_id to POST /v1/my/images.
Body
purposestringimportimagemedia_assetSet to import for CSV contact imports, or image/media_asset for image media assets.
blobobjectrequiredResponse
Direct-upload reservation
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List import jobs
Parameters
pageinteger1querylimitinteger<= 10025queryResponse
Paginated import jobs
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start a CSV import
Enqueues an import job from an Active Storage direct-upload signed_id.
Create the blob through POST /v1/direct_uploads with purpose=import,
PUT the file to the returned direct-upload URL, then submit the returned
signed_id here. Poll GET /v1/my/imports/{id} for status, row counts, and row-level errors.
For contact imports, pass options as a JSON object or JSON string
with list_ids to assign imported contacts to one or more lists,
e.g. {"list_ids":[88]}.
Imports start no flows unless options.start_flows is true. Then
each committed batch starts live New contact flows for the contacts
the import creates and live Add to list flows for its new list
members. Without it, the import's flows_not_started names the live
flows it would have started.
Body
signed_idstringrequiredActive Storage blob signed ID returned by /v1/direct_uploads.
resourcestringcontactsleadscontactsparserstringdefaultdefaultdry_runbooleanfalsecolumnsobject | string | nullCSV target-to-source-header mapping as a JSON object or JSON string. A null or blank target explicitly skips that field.
Default contacts CSV supports email_status, email_opt_out and
historical opt_in_at in addition to profile/custom fields.
Recognizable unsubscribe values are honored even when their column is
skipped, mapped as custom data or omitted by an older client. Unmapped
positive values do not assert consent. Dates require an explicit
mapping when any mapping exists. With no mapping, aliases are read automatically.
Status cells are trimmed and case-insensitive; values are finite:
email_status: subscribed/true/yes/1 = source-positive;
unsubscribed/false/no/0/opted out = source-negative.
email_opt_out is inverse: true/yes/1/unsubscribed/opted out = negative;
false/no/0/subscribed = positive. Blank cells mean unspecified.
Agreeing declarations resolve together. A valid negative wins over
other conflicting or unknown declarations in the same row with a
warning. Otherwise unknown status rejects only that row with
invalid_consent. Mapping the same source to both inverse targets
rejects rows with a nonblank value rather than inventing an opt-out.
An explicit negative unsubscribes the named brand/account email channel for new or existing contacts. Email remains the contact identity; phone sharing and list resolution are unchanged. Positive status and dates are source information, never re-consent. Omitted/positive status preserves existing consent. Existing channel history, including a missing opt-in date, stays unchanged. Delivery suppression remains independently authoritative and is never cleared. Imported opt-outs are retained in the existing address stop store.
options.email_action can unsubscribe all email addresses from marketing, or block all delivery with a manual brand-specific stop. Neither mode changes SMS consent or another brand.
opt_in_at accepts YYYY-MM-DD (00:00 UTC, day precision) or
YYYY-MM-DDTHH:MM:SS[.fraction] with Z or a numeric offset (+/-HH:MM or
+/-HHMM). Invalid calendar/time values, future dates, missing timezone,
non-ISO or disagreeing date sources are ignored with a warning; they
never discard a valid negative or reject the row. Historical dates
initialize new email channels only. A negative-first new email has
no opt-in date unless supplied; otherwise the existing new-email
default uses supplied history or observation time. Later negatives
preserve that history and the first opt-out time. Later positives or
dates cannot undo negatives, within or across flushes. Phone defaults
are unchanged. With usable phone but no usable email, email consent
and date facts are ignored with a warning; neither usable still fails
normal channel validation.
optionsobject | stringImport options as a JSON object or JSON string.
Response
Import queued
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get import schema metadata
Parameters
resourcestringcontactsleadsqueryOptional resource name. Omit to list all schemas.
Response
Import schema metadata
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get import job status
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete an import record
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Cancel a pending or processing import
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Exports
Contact CSV export jobs
List export jobs
Parameters
pageinteger1querylimitinteger<= 10025queryResponse
Paginated export jobs
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start a contact export
Enqueues an export job that builds a CSV of the brand's contacts and
attaches it to the export record. The same filters as GET /v1/my/contacts are supported (search, list_id, tag). Custom
fields stored on contacts are emitted as additional CSV columns.
Poll GET /v1/my/exports/{id} until ready is true, then download
the file from the returned download_path.
Body
resourcestringcontactsleadscontactssearchstringFree-text filter, matching the contacts list search.
list_idintegerRestrict the export to contacts in this list.
tagstringRestrict the export to contacts with this tag.
Response
Export queued
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get an export job
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Download a completed export file
Returns the CSV file once the export status is complete.
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Lists
Contact lists
List contact lists (paginated)
Parameters
namestringqueryExact case-insensitive list name filter
pageinteger1querylimitinteger<= 10025queryResponse
Paginated contact lists
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a contact list
Body
namestringrequiredsegment_idinteger | nullcontact_idsArray<integer>Response
List created
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a contact list
Parameters
idintegerrequiredpathResponse
Contact list
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a contact list
Parameters
idintegerrequiredpathResponse
Deleted list
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a contact list
Body
namestringsegment_idinteger | nullcontact_idsArray<integer>Parameters
idintegerrequiredpathResponse
Updated list
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get delete warning metadata for a contact list
Parameters
idintegerrequiredpathResponse
Flows connected to this list
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Add or remove existing contacts from a list by email
Public REST equivalent of the list membership batch primitive. The
endpoint resolves existing contacts by email within the current brand
and adds or removes memberships idempotently. It does not create
contacts; emails with no current-brand contact are returned in
not_found.
Body
actionstringaddremoverequiredAdd existing contacts to the list or remove them from it.
emailsArray<string>requiredParameters
idintegerrequiredpathResponse
Bulk list membership result
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Segments
Dynamic contact segments
List all segments (paginated)
Parameters
pageinteger1queryperinteger<= 100100queryResponse
Segments
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a segment
filters must contain at least one condition. Empty filters ([],
{} or a group with no conditions) would match every contact, so they
are rejected with a 422 and validation_errors.filters. To reach
every contact, target the All contacts audience instead of a segment.
Body
namestringrequiredfiltersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGrouprequiredRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
Response
Segment created
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a segment
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a segment
Parameters
idintegerrequiredpathResponse
Deleted segment
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a segment
An update cannot remove every filter condition from a segment that has
conditions; that returns a 422 with validation_errors.filters.
Segments stored without conditions before this rule can still be
renamed or re-saved with empty filters.
Body
namestringfiltersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
Parameters
idintegerrequiredpathResponse
Updated segment
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Count contacts matching filters
Preview how many contacts match a set of segment filters without creating or saving a segment.
Body
filtersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
Response
Contact count
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Preview contacts matching filters
Preview a prospective segment without saving it. Returns a live count,
a bounded contact sample, and bounded overlap with existing segments.
Invalid filters fail closed with invalid_filter.
Body
filtersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
Response
Segment preview
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Campaigns
Email and SMS campaigns
List campaigns (paginated)
Parameters
pageinteger1querylimitinteger<= 10025queryResponse
Paginated campaigns
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a campaign
Body
namestringrequiredchannelstringemailsmsemailResponse
Campaign created
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a campaign
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a campaign
Parameters
idintegerrequiredpathResponse
Deleted campaign
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a campaign
Updates the campaign. When the campaign is no longer editable (see the
editable field on the Campaign schema — false for live/paused/
completed/cancelled/archived, and for scheduled campaigns within 5
minutes of their send time), only name-only payloads and status
transitions (Resume, Cancel) are accepted. Any other attribute returns
422 with error_code: "campaign_locked". Use the /duplicate endpoint
to fork a sent campaign into a new draft. In Setup mode a move to
live or scheduled, including a resume, returns 402 plan_required
before anything changes.
Body
namestringstatusstringchannelstringemailsmsscheduled_atstring<date-time> | nulltrigger_attributesobjecttemplate_attributesobjectParameters
idintegerrequiredpathResponse
Updated campaign
Live sending needs a plan (error_code: plan_required). The account is in Setup mode: its work is saved and test sends still work, but no live email goes out until it is on Starter or above. Nothing was sent, queued, scheduled, approved or published. Show plan_url to the user (it opens the plan choice in Billing) and send again once the plan is active. Retrying before then returns the same refusal.
Template version conflict
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Duplicate a campaign
Creates a new draft campaign that copies the source's audience (trigger.audience_type, contact_list_ids, segment_id, exclude_segment_ids, exclude_contact_list_ids) and template content (design, subject, preheader, body, from_name, from_email, reply_to). Resets status to draft, approval_state to pending_review, scheduled_at to null, and trigger.event to manual. Works on any status — this is how clients fork a sent campaign into a new draft. Sessions, activities, approvals, and metrics are not copied.
Pass cancel_source: true to atomically cancel the source campaign
in the same transaction as the duplicate — useful for 'cancel and
duplicate' flows on paused campaigns.
Body
cancel_sourcebooleanfalseWhen true, cancels the source campaign in the same DB transaction as the duplicate creation.
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Render a campaign email to HTML
Renders the campaign's current template through the shared preview renderer.
Parameters
idintegerrequiredpathResponse
Rendered HTML
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read saved campaign readiness and capacity guidance
Read-only structural checks and the deduplicated saved audience count. Capacity warnings are informational, not approval or admission gates. Email drafts also include an informational allowance for new content reviews; previously reviewed content and exempt workloads may remain eligible. Save pending draft changes before requesting this projection.
Parameters
idintegerrequiredpathResponse
Structural readiness with optional capacity guidance
Resource not found
A read did not finish within the request's database time limit (error_code: query_timeout). Nothing was changed; retry after the Retry-After interval. Any GET can return this.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Ask for suggested alternatives to the subject line
Asks NitroLLM for suggested alternatives to the campaign's subject line, for its current content. Saving content already asks, so call this only when readiness versions.status is none. Asking again for the same content changes nothing. Poll readiness for the lines.
Parameters
idintegerrequiredpathResponse
The request's state for the current content
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get current campaign delivery progress
Polls the current campaign send using the same Campaign::SendProgress
payload exposed on the campaign serializer. Active sends return
status: "sending" with poll_after_seconds; a send waiting for a
person's approval returns status: "awaiting_approval". Terminal sends
return status: "completed" or status: "failed" once the attempt has
finished, even if it was stopped first, status: "cancelled" for a
cancelled or archived campaign, and status: "paused" while a stopped
attempt is retained unfinished (a manual pause or a deliverability
guard). Campaigns that have not started delivery return
status: "not_started". Polling also refreshes server-side progress:
queued reservations older than 15 minutes are marked failed before the
response is returned, so failed/pending can change on a poll even
when no provider webhook has arrived.
Parameters
idintegerrequiredpathResponse
Current campaign delivery progress
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Send a test email for a campaign
Thin adapter over the same test-send service used by template tests.
Use contact_id to send directly to a contact, or
sample_contact_id to personalize explicit test recipients without
sending to that contact. The two contact parameters are mutually
exclusive.
Test emails go to the account's own people (owner, members, an active
managing account's people) and to addresses at the account's verified
domains. Up to 10 other addresses per 30 days are allowed; past that,
each refused recipient is reported in results with status: failed
and the reason in error, and the other recipients still receive the
test.
Supply one fresh Idempotency-Key for each user-initiated send and
reuse that exact key for transport retries.
Body
emailstring<email>emailsArray<string>send_test_toArray<string>contact_idintegersample_contact_idintegerContact whose projected data personalizes the test without changing the test recipient.
event_dataobjectSample data for event fields in this test (max 32KB); never records an Event or Order. Campaign products remain fixed, not event-bound.
Parameters
idintegerrequiredpathIdempotency-KeystringrequiredheaderResponse
Test email sent
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Send a campaign
Delivers the exact persisted campaign snapshot. Save content, audience,
and other authoring changes through the campaign update endpoint first.
This endpoint rejects authoring fields rather than merging them during
delivery. Pass deliver_at (RFC 3339) to schedule; omit it to send now.
Both expected_campaign_updated_at and template_if_version are
required so a stale caller cannot send a newer draft accidentally.
Returns 422 campaign_locked if the campaign is not editable
(live, paused, completed, cancelled, archived, or scheduled within
5 minutes of send). Returns 409 duplicate_campaign_schedule or
duplicate_campaign_send when a repeat attempt would create another
schedule or overlap an active send; poll /delivery, cancel, or edit
the existing scheduled campaign instead. In Setup mode a send or a
schedule returns 402 plan_required before anything is approved or
queued.
Body
expected_campaign_updated_atstring<date-time>requiredExact campaign.updated_at value from the persisted draft being approved for delivery.
template_if_versionintegerrequiredExact persisted campaign template version being approved for delivery.
deliver_atstring<date-time>Future delivery time. Omit for immediate delivery.
confirm_send_to_allbooleanRequired when the persisted audience is all_contacts.
versionsArray<CampaignVersionInput>Other subject lines to test against the campaign's own (version A, never listed). Two versions need 1,000 recipients, three 2,500, five 5,000 and six 20,000. Returns 422 invalid_campaign_versions when they don't fit.
winnerCampaignWinnerInputSend the versions to a test part of the list, then the winning version to the rest after the wait. Omit to split everyone. When nothing clearly wins, the rest gets the campaign's own subject line.
Parameters
idintegerrequiredpathResponse
Campaign sent
Live sending needs a plan (error_code: plan_required). The account is in Setup mode: its work is saved and test sends still work, but no live email goes out until it is on Starter or above. Nothing was sent, queued, scheduled, approved or published. Show plan_url to the user (it opens the plan choice in Billing) and send again once the plan is active. Retrying before then returns the same refusal.
Template version conflict or duplicate send attempt
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Workspace
Read-only next actions, agent activity and bounded workspace search
Read the current brand's next actions and work in progress
Projects existing operational records, actionable items first. Does not create tasks, count audiences, approve actions or initiate sending. Chat confirmations are restricted to the authenticated user. Completed work leaves this projection. Each page contains at most 20 items.
Parameters
pageinteger[1, 100]1querythroughbooleanfalsequeryReturn the prefix through this page to refresh an expanded queue in one read.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read agent and API control-plane activity for the current brand
Reuses recorded MCP and in-app tool calls plus supported REST mutations. Returns up to 25 entries in descending ID order. Prompts, arguments, results and secrets are excluded. Outcome describes the requested action, never email delivery. Individual deliveries remain in the Sending log. Unrecorded historical API operations cannot be reconstructed.
Parameters
sourcestringmcpnitrollmapiqueryoutcomestringokerrorunknownquerybeforeinteger>= 1queryRead older entries using the previous response's next_cursor.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Search the current brand beyond locally loaded pages
Returns at most five matches each for campaigns, flows, contact lists and contacts. No total counts or audience calculation. A database statement exceeding one second returns a retryable timeout, not a misleading empty result. Queries shorter than two characters return no items.
Parameters
qstringqueryResponse
Bounded matches with application navigation targets
Not authorized
Search timed out; retry without treating this as an empty result.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Messages
Transactional email and SMS messages
List messages
Returns all messages by default. Use source_type to narrow to campaign, flow, transactional, or test sends.
Parameters
source_typestringallcampaignflowtransactionaltestqueryFilter by source. Omit or use 'all' for everything.
flow_idintegerqueryFilter to messages from a specific flow
campaign_idintegerqueryFilter to messages from a specific campaign
datestring<date>queryFilter to messages created on this date
channelstringemailsmsquerystatusstringqueuedsentfailedquerypageinteger1querylimitinteger<= 10025queryResponse
Paginated list of messages
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Send a transactional message
Send a transactional email or SMS to a single recipient immediately.
Email safety review applies to each new canonical content identity, including
established senders. Personalized copies reuse the same current finding.
Unsupported institutional authority remains unsent for review. An email the
safety check can't read (an image that doesn't load, too many images, an email
too long to check, or markup it can't read) is refused at once with 422
image_unavailable or content_needs_changes, naming each image and the fix;
no review is opened. Use the existing image ingestion API for external images;
a platform-hosted sender or a self-entered website does not prove institutional authority.
No campaign, no audience, no approval required.
Use for receipts, password resets, OTPs, order confirmations, and system notifications.
Requires an idempotency key via the Idempotency-Key header or the
idempotency_key body field. Reuse a key only for an exact retry: the
same key with the same payload returns the original message, and with
a different payload returns 409.
A top-level field not listed in the request body is ignored and named
in the response's ignored_fields; an otherwise valid request is
created and sent as usual. When a request made with an API key
carries such fields, the account owner gets an email, at most once a
week, naming the key and the fields.
Body
channelstringemailsmsrequiredtostringrequiredRecipient email address or E.164 phone number
ccArray<string>Visible email copies. Each distinct recipient consumes an email credit, daily allowance and sending capacity. Email only.
bccArray<string>Hidden email copies, omitted from delivered headers. Counted toward usage just like To and Cc. Email only.
subjectstringEmail subject line (required for email channel)
bodystringMessage body. Required for SMS. For email this is plain text (HTML in this field is escaped) and serves as the plain-text alternative when html is set. To send HTML, use html or template_id.
htmlstringPre-rendered HTML body for email, used verbatim as the HTML part (not escaped). Use this to send your own fully-rendered HTML. Mutually exclusive with template_id (email only). Personalization syntax inside ordinary HTML comments is ignored; visible and Outlook conditional content is validated.
template_idintegerLoad email design from an existing template (email only)
contact_idintegerOptional contact to personalize with when rendering a template
fromstringVerified sender email for this email message. May include a display name, for example "Acme hello@example.com".
from_emailstringVerified sender email for this email message. Alias of from.
from_namestringSender display name for this email message
reply_tostringReply-to email address for this email message
headersobjectProvider headers for this email message. Structural and Nitrosend-reserved headers are rejected.
tagsobjectProvider tags for this email message. Nitrosend-reserved tag keys are rejected and system tags are always controlled by Nitrosend. For SES senders, names and values may contain only ASCII letters, numbers, underscores and hyphens, up to 256 characters. Unsupported tags return 422 before queuing.
dataobjectMerge variables
mail_actionMailActionDescriptionA Mail Action Protocol 0.3 description of any type. Nitrosend parses it as MAP JSON within the core limits, validates it against the canonical MailSchema core schema and adds it as a designated application/ld+json part in a partial multipart/related representation. Delivery requires a raw-message provider. The description carries no service credential or authorization grant.
idempotency_keystringStable idempotency key (alternative to the header). One of the two is required.
Parameters
Idempotency-KeystringheaderRequired unless idempotency_key is supplied in the body. Prevents duplicate sends on retry. The same key with the same payload returns the original message; the same key with a different payload returns 409.
Response
Existing message returned for idempotency replay
Message created
Missing idempotency key (idempotency_key_required).
Live sending needs a plan (error_code: plan_required). The account is in Setup mode: its work is saved and test sends still work, but no live email goes out until it is on Starter or above. Nothing was sent, queued, scheduled, approved or published. Show plan_url to the user (it opens the plan choice in Billing) and send again once the plan is active. Retrying before then returns the same refusal.
Idempotency conflict or explicit sender selection required; no new message is retained in either case
Validation failed, or the send was refused. When the message itself is invalid, the body also lists the request's ignored top-level fields in ignored_fields. When the safety check couldn't read the email (error_code image_unavailable or content_needs_changes), the body carries reason_code, how_to_fix and details.
Admission evidence or the shared hosted-sender root is temporarily unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Sending log rows, filter counts and email engagement (Activity)
Groups the brand's messages into Sending log rows: one per campaign, one per standalone flow, and one per creation day for transactional messages and for test sends. A since window selects messages by the time they were sent, or by the time they were created while they have no send time (queued or failed messages). This is the same window as the email engagement cohort. One request time anchors every part of the response. engagement is the engagement of the emails the provider accepted in that window for the same source (test sends excluded), counted once per email. Each campaign, flow and transactional row takes its delivered, opened, clicked and rates from it, so on those rows opened <= delivered <= sent. Rows of the failed-only view (failed=true) list no accepted email and report no engagement. Rows are ordered by last send and limited by limit, while engagement.summary covers every email in the window, so row sums can be below it. Responses are cached for 45 seconds.
Parameters
source_typestringcampaignflowtransactionaltestqueryRestrict to one source. Omit for every source.
sincestringtoday7d30d3mqueryWindow by send time (creation time while unsent). Omit for all time.
failedbooleanqueryOnly failed messages. Their rows report no engagement.
campaign_idintegerqueryOnly messages of this campaign's flows.
limitinteger[1, 100]50queryMaximum rows (1-100, default 50). Counts and engagement are not limited.
Response
Sending log rows, filter counts and the Activity engagement.
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a transactional message
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Render a message subject and HTML for preview
Returns the as-composed subject and HTML for an email message from any send source. The stored subject is interpolated with the same preview merge context as its template (rendered design), raw html, or escaped plain-text body. Stored message fields are not changed. This is a current preview, not a historical delivered-message snapshot. Non-email or unrenderable messages (deleted/design-less template) return a typed empty body state (empty: true) rather than an error; an email subject can still be rendered when the body is empty.
Parameters
idintegerrequiredpathResponse
Rendered preview, or a typed empty state.
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Suppressions
Account suppression list and deliverability diagnostics
List suppressions
Returns the authenticated account's current suppression records by default, including bounded provider diagnostics when the source feedback event is available.
Parameters
idintegerqueryFilter to a specific suppression ID
emailstring<email>queryFilter to a specific suppressed email address
reasonstringhard_bouncesoft_bouncecomplaintmanualadminunsubscribeverificationmarketing_withheldunconfirmedquerysource_providerstringqueryFilter by provider that emitted the source event
activebooleantruequeryDefaults to true. Set false to list expired suppressions.
pageinteger1querylimitinteger<= 10025queryResponse
Paginated list of suppressions
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Webhooks
Signed delivery-event webhooks for transactional email
List webhooks
The current brand's webhook endpoints, oldest first, each with its newest delivery. Secrets are masked.
Parameters
pageinteger1querylimitinteger<= 10025queryResponse
Paginated list of webhooks
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Register a webhook endpoint
Registers an HTTPS endpoint to receive the chosen events for the
brand's transactional email. The response carries the signing secret
in full; later reads mask it unless reveal=true. A brand can have at
most 10 webhooks. The URL must resolve only to public addresses.
Body
urlstring<uri>HTTPS URL that resolves only to public addresses, without credentials.
eventsArray<WebhookEventType>email.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledenabledbooleanResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a webhook
Parameters
idintegerrequiredpathrevealbooleanfalsequeryReturn the signing secret in full.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a webhook and its delivery history
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a webhook
Changes the URL, the events, or whether the webhook is on. Turning it off fails the deliveries it still owed; turning it on clears its failing state. Events that occur while it is off are not sent.
Body
urlstring<uri>HTTPS URL that resolves only to public addresses, without credentials.
eventsArray<WebhookEventType>email.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledenabledbooleanParameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Send a test event
Queues a sample event of the chosen type to this webhook through the
normal delivery path, signed and retried like a real event. Its data
carries test: true and no message id.
Body
typeWebhookEventTypeemail.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledParameters
idintegerrequiredpathResponse
Test event queued
Resource not found
Unknown event type, or the webhook is off
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List a webhook's deliveries
The last 7 days of deliveries to this webhook, newest first.
Parameters
idintegerrequiredpathpageinteger1querylimitinteger<= 10025queryResponse
Paginated list of deliveries
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Templates
Email templates, preview, and component schema
Ingest an image media asset
REST adapter over the same image ingest capability used by MCP. Send
exactly one source: image_data, image_url, multipart file, or a
direct-upload signed_id created with purpose image or media_asset.
The v1 media contract supports media_kind: image only.
Body
application/jsonobjectimage_datastringRaw base64 image bytes or a data URL. PNG, JPEG, GIF, or WebP only; decoded size must be under 10MB.
image_urlstring<uri>Public PNG, JPEG, GIF, or WebP URL to ingest when Nitro-hosted permanence is desired.
signed_idstringActive Storage blob signed ID returned by /v1/direct_uploads after uploading bytes with purpose image or media_asset.
filenamestringOriginal filename for image_data uploads, or optional filename override for image_url/signed_id sources.
content_typestring | nullOptional MIME type hint when image_data is raw base64 rather than a data URL.
multipart/form-dataobjectfilestring<binary>PNG, JPEG, GIF, or WebP file upload. Must be under 10MB.
filenamestringOptional filename override.
content_typestring | nullOptional MIME type override.
Response
Ingested image asset
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List all templates (paginated)
Returns a summary view with section counts (not full design).
Parameters
pageinteger1queryperinteger<= 100100queryscopestringallstandaloneallqueryUse standalone for reusable library templates. Omit or use all to retain the complete designed-template result.
include_previewsbooleanqueryWhen set, each summary includes rendered preview_html (cached per template version)
Response
Template summaries
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a standalone template
Creates one standalone template. Idempotency-Key is required; an exact retry returns the original template, while reuse with changed input returns 409.
Body
namestringsubjectstringbodystringAuthor text in plain format; custom text alternative in designed format.
content_formatEmailContentFormatdesignedplainDurable email presentation. New templates default to designed; omitted edits preserve the stored value. A supplied value must equal the stored format for edits or the authorized selected source format for copies; newly authored Flow content can select designed or plain. AI composition retains its own authorized source-format contract. Null, invalid and mismatched edits fail validation. Plain uses body as author text and produces minimal HTML plus a real text alternative, with required compliance and current Brand tracking policy. It is not no-HTML MIME. Only email templates support plain. This differs from message format, which describes its template/raw/plain source shape.
plain_text_modestringderivedcustompreheaderstringgeneration_provenanceGenerationProvenanceCandidate-bound generation evidence. Save endpoints accept only
state: candidate values returned by the generation endpoint. Resource
responses may return state: accepted as read-only history.
if_versionintegerRequired optimistic concurrency token. Use the current template.version.
designEmailDesignEmail template design document
catalog_idstringThe gallery template a saved guest draft started from. Not stored; a known catalog id is recorded once for the first creation under this Idempotency-Key, and an unknown or absent one never fails the save.
Parameters
Idempotency-KeystringrequiredheaderResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a template with full design
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete an unused standalone template
Parameters
idintegerrequiredpathif_versionintegerrequiredqueryRequired optimistic concurrency token. Use the current template.version.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a template
Body
namestringsubjectstringbodystringcontent_formatEmailContentFormatdesignedplainDurable email presentation. New templates default to designed; omitted edits preserve the stored value. A supplied value must equal the stored format for edits or the authorized selected source format for copies; newly authored Flow content can select designed or plain. AI composition retains its own authorized source-format contract. Null, invalid and mismatched edits fail validation. Plain uses body as author text and produces minimal HTML plus a real text alternative, with required compliance and current Brand tracking policy. It is not no-HTML MIME. Only email templates support plain. This differs from message format, which describes its template/raw/plain source shape.
plain_text_modestringderivedcustompreheaderstringif_versionintegerrequiredRequired optimistic concurrency token. Use the current template.version. A stale value returns 409 with current_version and expected_version.
from_namestringfrom_emailstring<email>reply_tostring<email>generation_provenanceGenerationProvenanceCandidate-bound generation evidence. Save endpoints accept only
state: candidate values returned by the generation endpoint. Resource
responses may return state: accepted as read-only history.
designEmailDesignEmail template design document
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Render an existing template to HTML
Renders the template through the shared preview renderer.
Parameters
idintegerrequiredpathResponse
Rendered HTML
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Send a test email
Send a test email for the given template. Provide email for an
explicit recipient, contact_id to use a contact's email (with
merge-tag personalization), or sample_contact_id to personalize an
explicit test recipient without sending to the contact. contact_id
and sample_contact_id are mutually exclusive. Omit all recipient
inputs to use the brand's saved test recipients, falling back to the
account owner.
Test emails go to the account's own people (owner, members, an active
managing account's people) and to addresses at the account's verified
domains. Up to 10 other addresses per 30 days are allowed; past that,
each refused recipient is reported in results with status: failed
and the reason in error, and the other recipients still receive the
test.
Supply one fresh Idempotency-Key for each user-initiated send and
reuse that exact key for transport retries.
Body
emailstring | Array<string>emailsArray<string>send_test_toArray<string>contact_idintegersample_contact_idintegerContact whose projected data personalizes the test without changing the test recipient.
Parameters
idintegerrequiredpathIdempotency-KeystringrequiredheaderResponse
Test email sent
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Render an email document to HTML
Body
event_dataobjectOriginal trigger data used only for this preview (max 32KB).
documentobjectrequiredSource-free preview preserves the designed default; selecting plain is not accepted.
Response
Rendered HTML
Bad request
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get the email component schema
Returns the full schema for email design sections including all
component types, their props, required fields, and defaults.
Sourced from config/email_components.yml.
Response
Email component schema
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List the system template library
Returns the curated system template catalog. Each template ships two
faces: its original art direction (design/preview_html) and a
brand-matched variant with the palette overrides stripped so the
account's colors flow in (branded_design/branded_preview_html).
Sourced from the canonical catalog in config/email_templates/,
ordered by config/email_templates/index.yml.
Response
Library templates with original and brand-matched variants
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
AI-generate an email draft
Generate, regenerate, or refine a complete template, campaign-email, or selected flow-email draft through the same authoring spine. This never persists or sends. A flow target addresses exactly one existing email action, never the whole flow. Reusing an idempotency key with changed authoring input returns a conflict.
Body
goalstringrequiredWhat the email should accomplish
Welcome new subscribers and introduce the brandoperationstringgenerateregeneraterefinerequirededit_scopestringcopydesignbothDefaults to copy for refine and both otherwise.
user_instructionstringcategorystringOptional category hint (welcome, newsletter, promotion, etc.)
tonestringOptional tone override (formal, casual, etc.)
current_draftobjectrequiredComplete unsaved editor state to generate or refine. Supplied format must match the scoped stored/source format; unbound new content defaults to designed.
authoring_targetobjectrequiredParameters
Idempotency-KeystringrequiredheaderRetry-stable identity for this generation request.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Flows
Automation flows and step schema
Save an edited guest flow after sign-in
Copies an anonymous demo draft and its scanned Brand Kit into the authenticated account. Only the ready draft of the demo's current revision can be claimed. The guest token is scoped to one 24-hour demo; exact retries return the same flow. The copied flow remains a draft and does not send until separately approved and activated.
Body
tokenstringrequirednamestringsend_testsbooleanfalseSend every email step of the claimed flow as a test to the signed-in user's own address, in flow order. Queued after the claim; each step is sent at most once per flow.
graphobjectrequiredParameters
Idempotency-KeystringrequiredheaderResponse
Claimed draft flow and target Brand
The same demo was claimed with different input or by another account
Expired demo, no ready draft for the current revision, invalid graph, or Brand limit reached
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List automation flows (paginated)
Returns standalone flows only (excludes campaign-attached flows).
Parameters
pageinteger1querylimitinteger<= 10025queryResponse
Paginated flows
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a flow
Creates a draft flow without delivery authority. Idempotency-Key is required; an exact retry returns the original flow, while reuse with changed input returns 409. Approve or activate in a separate request.
Body
Parameters
Idempotency-KeystringrequiredheaderResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Write a draft flow for the brand from a goal or a template
Send a goal or a template_id. A goal is planned into the flow's trigger,
waits, checks and emails; a template (one whose brand_writable is true
in GET /v1/my/flow_templates) keeps its own. Every email is then written
for the current brand and the flow is saved as a pending-review draft,
using one AI generation. A template that starts on list_add needs
contact_list_id. Idempotency-Key is required: an exact retry returns
the original flow, a duplicate sent while the first is still writing
returns 409 generation_in_progress, and reuse with a changed request
returns 409 idempotency_conflict.
Body
goalstringtemplate_idstringA flow template id, sent instead of goal.
contact_list_idintegerThe brand list a list_add template starts on.
Parameters
Idempotency-KeystringrequiredheaderResponse
Exact idempotent replay of an existing flow
Flow written and saved as a draft
Bad request
The first request with this key is still writing, or the key was reused with a changed request
AI generation limit reached (ai_limit_reached), a template that cannot be written for the brand (invalid_template), a list template without its list (trigger_binding_required), or a goal that could not become a flow
Planning or writing failed; retry with the same key
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a flow
Parameters
idintegerrequiredpathinclude_blockersbooleantruequeryPass false to leave blockers out of unpublished_change, as
the flow list does, which skips the publish checks. Defaults to
true.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a flow
Parameters
idintegerrequiredpathResponse
Deleted flow
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a flow
Authoring (name, trigger, steps, generation_provenance) and
delivery control (status, approval_state) are separate requests and
must not be mixed. For graph writes, pass expected_draft_revision_id
from the latest flow read to reject stale authored changes.
An authoring save to a live or paused flow with publish: true
publishes the saved revision after the same checks as approval, and
Safe Mode for API keys. Without it, the save waits as a draft and
unpublished_change reports it. A live flow stays
live and a paused flow stays paused; contacts already in the flow keep
the version they started on. If a check refuses the publish, the save
is kept, the flow keeps running its last version, and the response's
unpublished_change says why. On a live or paused flow, approving the
current draft (approval_state: approved with its revision_id)
publishes it. A draft flow still goes live with status: live. Flow
approval/rejection and status: live publication from a draft flow
derive the current draft when revision_id is omitted. When supplied,
revision_id asserts that the named revision is still the current
draft; a stale assertion returns 409. On an already-live flow,
status: live without revision_id is a status no-op and does not
publish pending changes. Restarting a paused flow with contacts already
in progress requires resume_mode. A plain restart is refused when the
flow has unpublished changes; supply the current draft revision to
publish those changes as part of the restart.
In Setup mode, status: live, a restart and an approval that would
publish a live or paused flow return 402 plan_required before
anything changes. A save with publish: true is still kept: the flow
keeps running its last version and unpublished_change.blockers
includes plan_required.
Body
namestringstatusstringdraftlivepausedarchivedcancelledapproval_statestringapprovedrejectedrevision_idinteger | nullOptional current-draft assertion for approval_state and status=live publication. Omission derives the current draft for approval_state and for publication from draft status. On an already-live flow, status=live without revision_id is a no-op. Supply the current draft revision to publish pending changes while restarting a paused flow.
resume_modestringnew_contacts_onlycontinue_existingRequired when resuming eligible journeys. new_contacts_only stops them; continue_existing retains their schedule and existing sending limits. Live flows select only explicitly resumable blocked journeys.
expected_draft_revision_idinteger | nullExact optimistic concurrency token for authored graph changes.
updated_atstring<date-time>Optimistic concurrency check
triggerFlowTriggerInputstepsArray<FlowStepInput>generation_provenanceGenerationProvenanceCandidate-bound generation evidence. Save endpoints accept only
state: candidate values returned by the generation endpoint. Resource
responses may return state: accepted as read-only history.
publishbooleanfalseWith an authoring save to a live or paused flow, publish the saved revision. Ignored without authoring fields.
Parameters
idintegerrequiredpathResponse
Updated flow
Live sending needs a plan (error_code: plan_required). The account is in Setup mode: its work is saved and test sends still work, but no live email goes out until it is on Starter or above. Nothing was sent, queued, scheduled, approved or published. Show plan_url to the user (it opens the plan choice in Billing) and send again once the plan is active. Retrying before then returns the same refusal.
Conflict — the authored draft or requested publication revision is stale
Validation failed, or going live, resuming or publishing was refused. A refusal names the fix; when the safety check held or blocked a flow email, it can also say how to recover.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Preview the choices for restarting a paused flow
Parameters
idintegerrequiredpathResponse
Current restart impact and available choices
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get the flow step type schema
Returns the schema for flow step types, trigger events, and
audience filters. Flow steps and triggers are sourced from
config/flows.yml; filters are sourced from the audience filter
registry.
Response
Flow specification
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List flow templates
Returns the gallery templates available to the current account's enabled
capabilities. Filter the available templates with category.
Parameters
categorystringqueryReturn only this category's available templates, such as ecommerce.
Response
List of flow templates
Not authenticated
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a flow template
Returns a single flow template including the full trigger and steps
graph with its sample copy, ready to pass to POST /v1/my/flows. A template
whose needs_list is true also needs trigger.contact_list_id there.
Parameters
idstringrequiredpathFlow template slug (e.g. welcome)
Response
Flow template with full graph
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Mail Action Protocol
The account owner's review and decision of an agent's campaign send, described with MAP 0.3 Campaign Send Approval
Review a campaign send that waits for the account owner's approval
Under Safe Mode, an email campaign send requested by an agent, by sign-in or API key, waits for the account owner's approval. This is the current proposal: its state, the content it sends, and the MAP 0.3 Campaign Send Approval description of its exact terms. A MAP connector reads it before any decision. It takes a signed-in person's credential; an API key is refused.
Parameters
idintegerrequiredpathResponse
The send approval
Not authenticated
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Approve or decline a held campaign send at its terms version
The account owner or a direct account admin decides, naming the terms version the decision was made on (mail_action.terms.version). The service checks that version, the decider, the deadline, the plan, the sender's authorization and included email usage under the same locks that record the decision. Approval releases the send, now or at its scheduled time; decline cancels it. In Setup mode an approval returns 402 plan_required and the send stays pending, so it can still be declined. Repeating a recorded approval with its version returns it without sending again. A decision takes the person's own bearer sign-in: a browser cookie session, an impersonated session and an API key are refused.
Body
decisionstringapprovedeclinerequiredversionstringrequiredThe terms version the decision was made on.
Parameters
idintegerrequiredpathResponse
The send approval after the decision
Bad request
Not authenticated
Live sending needs a plan (error_code: plan_required). The account is in Setup mode: its work is saved and test sends still work, but no live email goes out until it is on Starter or above. Nothing was sent, queued, scheduled, approved or published. Show plan_url to the user (it opens the plan choice in Billing) and send again once the plan is active. Retrying before then returns the same refusal.
The caller cannot decide this send, or Nitrosend refuses the approval (error_code: approval_refused): the sender is no longer authorized, or the audience needs more email than the plan includes, since an approval never authorizes a charge. The send stays pending and can still be declined.
Resource not found
The send was already decided, changed since the given version, expired or was withdrawn. Nothing is applied.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Events
Contact event tracking
List events (paginated)
Parameters
pageinteger1querylimitinteger<= 10050queryeventstringqueryFilter by event type
contact_idintegerquerycreated_afterstring<date-time>querycreated_beforestring<date-time>queryresource_uidstringqueryresource_namestringquerytestbooleanqueryResponse
Paginated events
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Track a contact event
Requires an idempotency key via the Idempotency-Key header or
idempotency_key body param. Duplicate events (same account +
event type + idempotency key) return the existing event. When
contact_email names an email no contact in the brand holds, the
contact is created first and its "New contact" flows start before
the event's own flows.
order_placed and purchase also record an API Order when data.order_id
(or resource_uid) and data.total (or amount) are supplied. Amounts are
major units with at most two decimals, including zero; currency is a
three-letter code. Event and Order commit together. Missing identity or
total keeps event-only behavior; test events never write financial data.
order_canceled needs data.order_id. order_refunded additionally needs
data.refund_id and a positive incremental data.refund_amount; a refund id
applies once per order, and supplied currency must match. Use one
authoritative order feed per store: API, Shopify and Stripe ids are not
automatically matched across sources.
Body
eventstringrequiredEvent type name (lowercase, underscores)
contact_idintegercontact_emailstring<email>Alternative to contact_id, and used instead of it when both are sent. Resolves the brand's contact by email. When no contact holds the email, creates one subscribed by the collection default, or suppressed if the address is on the account's suppression list. An event never changes an existing contact's subscription.
idempotency_keystringIdempotency key (alternative to header)
amountnumber<double>resource_uidstringresource_namestringresource_urlstring<uri>testbooleanfalsedataobjectCustom event payload (max 32KB). Commerce may include order_id, total, currency, order_number, order_type, subtotal, tax, shipping and items. Use order_type=subscription_renewal for proven renewals (history/LTV, not attributed conversions). Product items use product_name/title, product_url, optional image_url and item_price in major units; original event data remains the flow context. Orders store at most 50 items with truncation metadata.
utm_sourcestringutm_mediumstringutm_termstringutm_contentstringutm_campaignstringParameters
Idempotency-KeystringheaderIdempotency key (alternative to body param)
Response
Duplicate event (idempotent — returns existing)
Event created
Bad request
Resource not found
The correction's order has not arrived. Retry after recording the purchase, using the same idempotency key; no event or phantom order is created.
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List event names for filter autocomplete
Returns known platform event names plus observed event names for the current brand.
Response
Event name suggestions
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get an event
Parameters
idintegerrequiredpathAuthorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete an event
Parameters
idintegerrequiredpathResponse
Deleted event
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Domains
Sending domain verification
List sending domains (paginated)
Parameters
pageinteger1queryperinteger<= 10030queryResponse
Paginated domains
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Add a sending domain
Initiates domain verification. Returns DNS records that must be
added at your domain registrar before calling POST /verify.
Retrying an already configured domain reconciles its stored DNS records
and preserves its DKIM key and verification state.
Body
domainobjectrequiredResponse
Domain registered with DNS records to configure
Validation failed
Domain setup is temporarily unavailable on Nitrosend's side. error_code: domain_setup_unavailable with retryable: true means Nitrosend's managed DNS cannot take the domain's records right now; Nitrosend has been alerted, and the same request can be retried later. Other 503s report a DNS delegation or email provider outage.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a domain with DNS records and status
Parameters
idintegerrequiredpathinbox_idintegerquerySelect one of this domain's inboxes for receiving setup and forwarding status.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Remove a sending domain
A paired domain first returns 422 with the exact counterpart impact.
Repeat with unpair=true only after the user confirms that outcome.
Parameters
idintegerrequiredpathunpairbooleanfalsequeryConfirm teardown of an identity pair after reviewing the paired-domain 422 response.
Response
Domain deleted
Domain is paired or still has dependent inboxes
Upstream service unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List shared subdomains and eligible destination brands
Requires the domain account owner or administrator. Brand-pinned API keys receive no destination directory. Sharing grants no access to the destination account's mail.
Parameters
domain_idintegerrequiredpathVerified apex or paired sending domain owned by the current brand.
pageinteger>= 11queryqstringqueryFilter the destination directory by brand or account name.
Response
Subdomains (25 per page) and up to 100 eligible destinations.
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Share an exact subdomain with a brand or managed client
Only the verified apex account owner or administrator can authorize sharing. Creates the recipient's own sending and visible-From identities and DKIM key; complete DNS verification through that brand's existing domain setup. The recipient uses its own domain and inbox allowances. Client ownership, payment, claim and management access requirements remain unchanged. Retrying the same subdomain and destination reuses its claim. Sharing again explicitly restores permission and binds the current managed relationship. Configured identities keep their existing DNS records, key and verification.
Body
subdomainobjectrequiredParameters
domain_idintegerrequiredpathVerified apex or paired sending domain owned by the current brand.
Response
Shared child claim; use the destination brand's domain setup to configure DNS.
Not authorized
Resource not found
Validation failed
Too many subdomain creation attempts. Retry later.
Upstream service unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Stop sharing a subdomain
Stops later sends and receiving, including work queued before revocation. Keeps historical mail and other subdomains intact. Requires the apex account owner or administrator.
Parameters
domain_idintegerrequiredpathidintegerrequiredpathResponse
Child claim with sharing stopped.
Not authorized
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Verify a domain
Reads the domain's DNS records and returns the domain with what is still outstanding, naming any required record that is missing. It is read-only and safe to repeat: once the required records are in place, Nitrosend asks the email provider and verifies the domain on its own. A call that finds the records newly in place makes that automatic check due at once, and repeating it never delays that check.
Parameters
idintegerrequiredpathResponse
The domain, its DNS health and what is outstanding
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create an Entri bootstrap session for domain DNS setup
Returns a short-lived Entri JWT plus the DNS record payload needed to launch the Entri modal for a domain owned by the current brand. An already-verified apex may request the prepared company-inbox MX cutover only with explicit approval and an exact domain-name confirmation.
Body
apex_mx_overridebooleanfalseExplicitly include the prepared company-inbox MX cutover in this session.
apex_mx_confirmationstringExact apex domain name being approved. Required when apex_mx_override is true.
Parameters
idintegerrequiredpathResponse
Entri bootstrap payload
Resource not found
Domain setup or apex mail cutover is not ready
Rate limit exceeded
Upstream service unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Configure inbound delivery for a verified domain
Selects exactly one inbound method for the current brand's verified
domain. Shared subdomains require current permission from the domain owner.
Provider forwarding keeps Google Workspace or Microsoft 365 as
the primary receiver and allocates one opaque Nitrosend forwarding
address. MX mode requires the domain to be ready for Nitrosend receiving;
apex domains additionally require a verified forward-all route.
Select an existing mailbox with inbox_id or its exact local_part.
With several inboxes, omitting a target is rejected. Creation continues
to enforce the current account policy; this endpoint does not buy capacity.
Body
inbound_setupobjectrequiredParameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Verify provider forwarding for a domain inbox
Shared subdomains require current permission from the domain owner.
Sends a challenge to the configured customer-facing inbox address. The
provider-forwarded copy must return through its bound opaque Nitrosend
address before the setup becomes active.
inbox_id is required when the domain has several inboxes.
Body
inbox_idintegerAn inbox belonging to this domain and brand.
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Integrations
BYO provider integration management
List integrations (paginated)
Parameters
categorystringemailsmscrmquerypageinteger1queryperinteger<= 10030queryResponse
Paginated integrations
Bad request
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create or connect an email provider integration
Body
integrationMailgunIntegrationInput | SesIntegrationInput | PostmarkIntegrationInput | ResendIntegrationInput | SendgridIntegrationInput | ActiveCampaignIntegrationInputrequiredResponse
Integration created
Bad request
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get an integration
Parameters
idintegerrequiredpathResponse
Integration
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Disconnect an integration
Mailbox connections stop their exact sender route and retain the source for audit and reconnect. Disconnect never switches a mailbox to SES. An active campaign, flow binding or unsettled selected-sender admission must be stopped or settled before its connection can be disconnected.
Parameters
idintegerrequiredpathconfirmbooleanrequiredqueryMust be true to confirm the destructive action.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update an email provider integration
Updates credentials or operational fields for an existing email provider. The provider cannot be changed once the integration exists.
Body
integrationMailgunIntegrationInput | SesIntegrationInput | PostmarkIntegrationInput | ResendIntegrationInput | SendgridIntegrationInput | ActiveCampaignIntegrationInputrequiredParameters
idintegerrequiredpathResponse
Integration updated
Bad request
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Test integration connectivity
A passing first test of a contact-sync integration that has never synced (ActiveCampaign) also starts its first sync.
Parameters
idintegerrequiredpathResponse
Tested integration
Resource not found
The provider refused the connection, for example "ActiveCampaign rejected the API key".
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Set an integration as the primary provider for its category
Parameters
idintegerrequiredpathResponse
Integration marked primary
Bad request
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get an integration's versioned profile sync contract
Parameters
integration_idintegerrequiredpathResponse
Safe sync configuration
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Validate and update an integration's profile sync contract
Body
Parameters
integration_idintegerrequiredpathconfirm_deselectionbooleanfalsequeryResponse
Updated safe sync configuration
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Discover safe provider objects and attributes for profile sync
Parameters
integration_idintegerrequiredpathResponse
Sync configuration and bounded provider discovery metadata
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start Attio OAuth connect flow
Returns an Attio OAuth authorize URL for the authenticated account/brand. The response URL includes a signed state payload and the API callback URI.
Response
OAuth authorize URL
Not authenticated
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start HubSpot OAuth connect flow
Returns a HubSpot OAuth authorize URL for the authenticated account/brand. The response URL includes a signed state payload and the API callback URI.
Response
OAuth authorize URL
Not authenticated
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Connect a Gmail, Google Workspace or Microsoft 365 sending mailbox
Returns the provider's authorization URL. Access belongs to one exact mailbox. A connection proves that exact address, including on a shared custom domain; it never claims the apex or provisions SES/DNS. Connecting does not change the selected sender or its existing provider.
Body
sending_domain_idintegerOptional existing brand domain to bind explicitly. A new connection without it is exact-address only.
return_tostringSigned allowlisted app-relative return path. External origins and traversal are rejected.
integration_idintegerExisting connection to reconnect without changing its mailbox.
Parameters
providerstringgmailmicrosoft365requiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Test SMTP and IMAP credentials and send an address verification code
Both connections must use verified TLS to public hosts. This creates a pending exact-address mailbox; it cannot send until verification succeeds. A pending connection may be retried with the same address and integration ID.
Body
integration_idintegerExisting pending SMTP connection.
mailboxobjectrequiredResponse
Pending mailbox connection; code sent to its address.
Not authenticated
Not authorized
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Activate a pending SMTP mailbox using its address verification code
Body
codestringrequiredParameters
idintegerrequiredpathResponse
Connected exact-address mailbox.
Not authenticated
Not authorized
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read this SMTP connection's feedback endpoint, signing secret, and recent receipts
Scoped to the current brand and SMTP connection. Secrets are encrypted at rest and returned only by this authenticated setup surface, with no-store caching. Existing connections receive a secret on first setup access. A received test confirms callback setup, not the provider's event coverage.
Parameters
idintegerrequiredpathResponse
SMTP feedback setup and the 20 most recent receipts.
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Replace this SMTP connection's feedback signing secret
The old secret is invalid immediately. Previously authenticated receipts still process.
Parameters
idintegerrequiredpathResponse
Setup with the replacement secret.
Not authenticated
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Receive signed delivery feedback for one SMTP connection
Sign the exact body using Standard Webhooks: HMAC-SHA256 of webhook-id + '.' + webhook-timestamp + '.' + body, using the base64-decoded whsec_ signing key. Send webhook-signature as 'v1,'. Timestamps must be within 300 seconds. Use the same webhook-id for retries, with a fresh signature/timestamp; reusing an ID for different content is 409. Maximum body size is 16 KiB. A 200 acknowledges durable receipt; processing uses the existing integration event queue. Retry non-2xx responses with backoff. Only an exact dispatched message, recipient, and connection can be updated. Late reports for existing sends remain accepted after sending is disconnected.
Body
typestringtestrequiredtypestringdeliveredbouncedcomplainedrequiredmessage_idstringrequiredOriginal RFC Message-ID, with or without surrounding angle brackets.
recipientstring<email>requiredoccurred_atstring<date-time>requiredOutcome time, no more than five minutes in the future.
statusstringRequired only for bounced events. Recipient failures suppress; policy failures remain delivery_failed observations.
nitrosend_message_idinteger<int64>[1, 9223372036854776000]Optional original X-Nitro-Message-Id, supplied together with dispatch_token to correlate an outcome before the send result is persisted.
dispatch_tokenstringOriginal X-Nitro-Dispatch header, supplied together with nitrosend_message_id.
Parameters
idintegerrequiredpathwebhook-idstringrequiredheaderUnique event ID, stable across retries.
webhook-timestampstringrequiredheaderUnix seconds at the time this attempt is signed.
webhook-signaturestringrequiredheaderResponse
Durable receipt accepted, including identical retries.
Invalid JSON, fields, timestamp, event type, or event data.
Unknown connection or invalid, missing, or stale signing credentials.
Event ID was previously used for different content.
Body exceeds 16 KiB.
Callback rate exceeded; retry with backoff.
Receipt or enqueue failed; retry the same event ID.
Complete a sending mailbox connection
Parameters
providerstringgmailmicrosoft365requiredpathstatestringrequiredquerycodestringrequiredqueryResponse
Redirect to the configured app connection-result page. It carries provider, status and a stable error_code on failure; signed authorized account/brand/return context only. The app confirms the saved Integration before returning. No raw provider error, OAuth code or token is exposed.
Start Shopify OAuth connect flow
Returns a Shopify OAuth authorize URL for the authenticated account/brand.
The request accepts a myshopify.com shop domain or shop slug. The
response URL includes a signed state payload and the API callback URI.
Public App Store connections require a direct account administrator and
always use Shopify billing. Custom app registrations remain bound to
their registered account, brand and shop.
Body
shopifyobjectrequiredResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Connect a merchant-owned Shopify app
Connects an API-only Shopify app owned by the same Shopify organization as its store. Nitrosend exchanges the client credentials server-side, verifies the authenticated shop and granted Admin API scopes, then stores the access token and client secret encrypted. Repeating the request for the same brand and shop verifies the new credentials before replacing the current connection. The response never includes client credentials or an access token.
Body
shopifyobjectrequiredResponse
Existing merchant-managed Shopify connection replaced
Merchant-managed Shopify connection created
Not authenticated
Missing fields, invalid credentials, missing scopes, or a shop ownership conflict
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start Stripe App OAuth connect flow
Returns the Nitrosend Stripe App install link for the authenticated
account and brand. The link carries a signed state and the API callback
URI; installing the app grants Nitrosend read access to customers,
subscriptions, invoices, charges, refunds and events. Pass mode: test
for the app's test-mode install link. No keys are pasted; tokens are
refreshed server-side. Events for connected accounts arrive on
/hooks/stripe_apps, isolated from Nitrosend billing webhooks at
/hooks/stripe.
Body
stripeobjectResponse
OAuth authorize URL
Not authenticated
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Public Stripe App install entry
The Stripe App Marketplace install URL. Sets a nonce cookie and redirects to the Stripe App install link for the requested mode. The callback provisions a Nitrosend account for a new email, or asks an existing user to sign in and connect from the integrations page.
Parameters
modestringlivetestlivequeryResponse
Redirect to the Stripe App install link
The Stripe App is not configured
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Stripe App OAuth callback endpoint
Public callback endpoint used by Stripe after the app is installed. Verifies signed state, exchanges the auth code with the mode-matched developer key, persists the integration and enqueues initial sync. A signed-in connect redirects to the app connection-result page; the public install door redirects into the app (new account) or to sign in (existing account).
Parameters
codestringquerystatestringqueryerrorstringqueryerror_descriptionstringqueryResponse
Public install redirect into the app or to sign in.
Redirect to the app connection-result page with safe result codes and authorized context.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Attio OAuth callback endpoint
Public callback endpoint used by Attio after user authorization. Verifies signed state, exchanges auth code, and finalizes Attio integration connection.
Parameters
codestringquerystatestringqueryerrorstringqueryerror_descriptionstringqueryResponse
Redirect to the app connection-result page with safe result codes and authorized context.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
HubSpot OAuth callback endpoint
Public callback endpoint used by HubSpot after user authorization. Verifies signed state, exchanges auth code, persists the integration, and enqueues initial sync.
Parameters
codestringquerystatestringqueryerrorstringqueryerror_descriptionstringqueryResponse
Redirect to the app connection-result page with safe result codes and authorized context.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Shopify OAuth callback endpoint
Public callback endpoint used by Shopify after user authorization. Verifies signed state, resolves the Shopify app from that signed state, verifies the app-specific OAuth HMAC, exchanges the auth code, persists the integration and app key, and enqueues initial sync.
Parameters
codestringquerystatestringqueryshopstringqueryhmacstringquerytimestampstringqueryerrorstringqueryerror_descriptionstringqueryResponse
Connected; public apps return to Shopify Admin, custom apps return to the Nitrosend integration
Invalid callback request
OAuth exchange failure
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Receive a Stripe App event for a connected account
Events from every Stripe account that installed the Nitrosend app,
delivered to the platform's connected-account webhook endpoint. The
signature is verified with the app endpoint secret (live or test),
the connection is resolved from account and livemode, and the
event is processed on that integration's execution lane. Events for
accounts that are not connected are acknowledged and dropped.
Body
Parameters
Stripe-SignaturestringrequiredheaderResponse
Verified event acknowledged
Invalid signature or unconfigured secret
Verified event could not be enqueued
Receive an App Store Shopify webhook
Uses the App Store app credentials when no app key is present.
Body
Parameters
X-Shopify-Hmac-Sha256stringrequiredheaderX-Shopify-Shop-DomainstringrequiredheaderX-Shopify-TopicstringrequiredheaderResponse
Verified webhook acknowledged
Invalid JSON payload
Invalid App Store HMAC
Verified webhook could not be applied
Receive a merchant-managed Shopify webhook
Resolves only active merchant-managed connections from the Shopify shop header and verifies the raw request body with that connection's encrypted client secret before parsing. Unknown shops, ambiguous ownership, missing secrets, and invalid signatures return the same response. Shopify Billing API topics are never processed on this route.
Body
Parameters
X-Shopify-Hmac-Sha256stringrequiredheaderX-Shopify-Shop-DomainstringrequiredheaderX-Shopify-TopicstringrequiredheaderX-Shopify-Webhook-IdstringheaderResponse
Verified supported webhook processed or unsupported topic safely acknowledged
Verified supported webhook contained invalid JSON
Webhook could not be authenticated
Verified webhook could not be applied
Receive a Shopify webhook for a named app
Body
Parameters
app_keystringcustomrequiredpathX-Shopify-Hmac-Sha256stringrequiredheaderX-Shopify-Shop-DomainstringrequiredheaderX-Shopify-TopicstringrequiredheaderResponse
Verified webhook acknowledged
Invalid JSON payload
Invalid app-specific HMAC
Verified webhook could not be applied
Open or resume the embedded Shopify app
Verifies the Shopify App Bridge ID token in the Authorization header, exchanges it for an offline Shopify access token when installation is required, and provisions or resumes the Nitrosend account integration. Subsequent embedded requests continue to authenticate with fresh Shopify ID tokens. An existing-account response never links by email. It includes a relative connect_path for ordinary Nitrosend sign-in and explicit account/brand confirmation before Shopify OAuth authorization.
Response
Embedded Shopify integration opened
Not authenticated
Embedded install needs recovery or cannot be opened
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Reconcile Shopify App Pricing after plan management
Parameters
shopstringrequiredqueryResponse
Redirect back to the app in Shopify Admin
Invalid Shopify shop domain
Brands
Brand context plus Brand Kit identity, theme, and per-brand configuration
List brands (paginated)
Brand-scoped credentials see only their own brand. Signed-in account users see their accessible account's brands.
Parameters
pageinteger1queryperinteger<= 100100queryResponse
All brands for the account
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a brand
Requires a signed-in account user. Brand-scoped credentials cannot create brands.
Body
namestringInternal brand name; mirrors company_name when company_name is omitted
brand_colorstringtext_colorstringbg_colorstringradiusinteger | null[0, 64]spacing_densitystring | nullcompactnormalspaciousfont_headingstringfont_bodystringheading_sizeinteger | null[12, 48]body_sizeinteger | null[12, 20]brand_documentstring | nullcompany_descriptionstringphysical_addressstringcompany_namestringlogostringSigned blob ID or URL
email_from_namestringemail_from_emailstring<email>email_reply_tostring<email>email_view_onlinebooleanemail_view_online_placementstringtopfooterWhere the View in browser link goes: at the top of the email, or beside the footer's Unsubscribe link.
email_track_opensbooleanInject the open-tracking pixel into this brand's emails.
email_track_clicksbooleanRewrite this brand's links for click tracking.
test_email_recipientsArray<string>linksArray<object>default_headerobjectdefault_themeobjectResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a brand
Parameters
sidstringrequiredpathBrand secure identifier
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a brand
Parameters
sidstringrequiredpathBrand secure identifier
forcestringtruequeryMust be true to delete a brand that has queued messages or scheduled/live campaigns.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a brand
Body
namestringInternal brand name; mirrors company_name when company_name is omitted
brand_colorstringtext_colorstringbg_colorstringradiusinteger | null[0, 64]spacing_densitystring | nullcompactnormalspaciousfont_headingstringfont_bodystringheading_sizeinteger | null[12, 48]body_sizeinteger | null[12, 20]brand_documentstring | nullcompany_descriptionstringphysical_addressstringcompany_namestringlogostringSigned blob ID or URL
email_from_namestringemail_from_emailstring<email>email_reply_tostring<email>email_view_onlinebooleanemail_view_online_placementstringtopfooterWhere the View in browser link goes: at the top of the email, or beside the footer's Unsubscribe link.
email_track_opensbooleanInject the open-tracking pixel into this brand's emails.
email_track_clicksbooleanRewrite this brand's links for click tracking.
sender_identity_idintegerReady brand-owned email sending identity to select through the canonical sender-selection authority.
sender_local_partstringVisible From local part for the selected sending identity.
test_email_recipientsArray<string>linksArray<object>default_headerobjectdefault_themeobjectParameters
sidstringrequiredpathBrand secure identifier
Response
Updated brand
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Reserve and prepare the Nitrosend sender
Reserves the brand's Nitrosend address when the brand has none (using the optional chosen subdomain and local_part, otherwise the company-derived name) and idempotently materializes the brand-owned logical Domain and sending identity under the verified shared nitrosend.net root. The operation is database-only: it makes no DNS, Vercel, Cloudflare, or SES call and never sends or retains email. A brand that already owns a namespace gets it back unchanged; the body is ignored because an allocated name is immutable.
Body
subdomainstringChosen subdomain label under the hosted apex; validated by the same policy as company-derived names.
local_partstringLocal part for the sender address (defaults to hello).
Parameters
sidstringrequiredpathBrand secure identifier
Response
The brand-subdomain sender is ready
The account or Brand Kit is not eligible, or the chosen name was rejected. error_code is one of subdomain_taken, subdomain_unsafe, local_part_invalid, brand_identity_required, brand_identity_review_required, sender_identity_limit_reached, sender_identity_retired, brand_inactive, sending_paused, subscription_inactive, principal_email_missing.
Address request rate or claim allowance reached. Retry-After specifies the wait in seconds.
The shared hosted-sender root is not release-ready; no identity or delivery state was written
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Change the brand's Nitrosend address name
Replaces the hosted subdomain while preserving the inbox, its history, and previous receiving addresses. Old names remain permanently owned; future replies use the new domain. Requires brand.manage authority and the current fqdn as a precondition. Active flow bindings and unsettled delivery work prevent a change. New claims share the account's existing lifetime allowance and are limited to two per brand per hour, including the initial claim. No DNS, SES or model calls occur during this operation. Changing the sender requires fresh clearance through normal send admission.
Body
subdomainstringrequiredRequested hosted address name
expected_fqdnstringrequiredCurrent brand_subdomain.fqdn
Parameters
sidstringrequiredpathBrand secure identifier
Response
Updated brand; an exact retry returns the same address
The address changed, or affected delivery work is still active. Nothing was changed.
The name is prohibited or taken, the account allowance is exhausted, or the inbox cannot preserve more addresses. Nothing was changed.
Request or claim rate exceeded. Retry-After specifies the wait in seconds.
The shared service is unavailable. Nothing was changed.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Check whether a Nitrosend address can be reserved
Advisory read for choosing the brand's Nitrosend address before it is reserved. Uses the same normaliser and uniqueness check as reservation, so the returned subdomain is exactly what prepare_sending would reserve. Never writes.
Parameters
sidstringrequiredpathBrand secure identifier
subdomainstringrequiredqueryRequested subdomain label under the hosted apex
local_partstringqueryRequested local part, checked with the same policy reservation applies; omitted means the allocator's default.
Response
Availability result
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get deletion safety for a brand
Returns authoritative deletion impact counts and active-send state for the confirmation UI.
Parameters
sidstringrequiredpathBrand secure identifier
Response
Brand deletion safety
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Scan a business website and apply its Brand Kit
Body
urlstringrequiredReal business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.
Parameters
sidstringrequiredpathBrand secure identifier
Idempotency-KeystringheaderReuse only for an exact retry of this website request.
Response
Admitted scan, including the same reference on an idempotent retry
Invalid idempotency key
Idempotency key already used for another website
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get brand onboarding state
Parameters
sidstringrequiredpathBrand secure identifier
Response
Onboarding state for the brand
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Complete a brand onboarding step
Body
stepstringbrand_kit_setupdomain_verifiedfirst_contactfirst_sendrequiredParameters
sidstringrequiredpathBrand secure identifier
Response
Updated onboarding state
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Start a website preview
A fresh brand's first scan is kept atomically. An existing kit remains available for explicit review and apply. Leaving the screen does not cancel the job.
Body
urlstringrequiredReal business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.
Parameters
sidstringrequiredpathBrand secure identifier
Idempotency-KeystringheaderReuse only for an exact retry of this website request.
Response
Admitted preview
Invalid idempotency key
Idempotency key already used for another website
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read the named or current brand scan
Parameters
sidstringrequiredpathBrand secure identifier
scan_idstringqueryOmit to recover this brand's current admitted scan. The reference survives transient progress-cache expiry.
Response
Current transient scan result
Unknown or expired progress. The setup center retains any admitted reference.
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Apply a selected website or file kit preview
Selects an existing completed preview for this brand. Saves only the selected fields and logo, together with the captured website assets and source reference. A newer source selected during asset preparation refuses the older save. No second website capture is performed.
Body
scan_idstringrequiredfieldsobjectSelected editable Brand Kit fields. Unselected captured fields are not applied.
include_logobooleanfalseAttach the website preview's captured logo.
logostringA signed uploaded logo blob, overriding the preview logo.
logo_candidate_idstringSelected candidate from a file kit preview.
template_idstringSelected template from a file kit preview.
Parameters
sidstringrequiredpathBrand secure identifier
Response
Selected kit saved atomically
A newer source superseded this save
Validation failed
Logo rendering is temporarily unavailable
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Email the account owner a one-time sign-in link
Sends the account's own address a link that signs its owner in on another device. It works once, lasts three days, and the latest link replaces any before it. Takes no recipient or redirect. Owner only, during an account's first week.
Parameters
sidstringrequiredpathBrand secure identifier
Idempotency-KeystringrequiredheaderResponse
Accepted
Missing idempotency key
Not the account owner, or past the first week
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Ask for the brand's welcome email
Writes the welcome email when the brand has none, again after a failure or once the Brand Kit is a different business; otherwise leaves it as it stands. Progress arrives in the setup center's welcome_email.
Parameters
sidstringrequiredpathBrand secure identifier
Response
Setup center state, with the welcome email's progress
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get brand setup center state
Parameters
sidstringrequiredpathBrand secure identifier
Response
Setup center state for the brand
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update brand setup center state
Body
Provide one of seen, dismissed, sender_choice, or card.
seenbooleandismissedbooleansender_choicestringownhostedcardstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdnsmetadataobjectParameters
sidstringrequiredpathBrand secure identifier
Response
Updated setup center state
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
SavedViews
Saved table presets (filters + sort + columns) per surface
List saved views visible to the current user
Returns all shared views in the current account plus the caller's own private views. Optionally filtered by surface.
Parameters
surfacestringcontactssendingactivityqueryFilter views by surface
pageinteger1querylimitinteger<= 10025queryResponse
Saved views
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Create a saved view
Creates a new saved view owned by the current user. Defaults to private visibility if not specified.
Body
surfacestringcontactssendingactivityrequirednamestringrequiredvisibilitystringprivatesharedprivatefiltersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
layoutSavedViewLayout | nullTable layout preset for contacts surface views. Only present when surface = contacts.
Response
Saved view created
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Delete a saved view
Deletes a saved view. Allowed only for the creator or the account owner. Other members receive 403.
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Update a saved view
Updates a saved view. Allowed only for the creator or the account owner. Other members receive 403.
Body
namestringvisibilitystringprivatesharedfiltersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
layoutSavedViewLayout | nullTable layout preset for contacts surface views. Only present when surface = contacts.
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Fork a saved view into a new private view
Clones an existing view (typically a shared view) into a new private view owned by the caller. The original is not modified.
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Public
Unauthenticated public endpoints
Ingest a Shopify Web Pixel event
Browser-safe public collector for Shopify Web Pixel standard events.
Requires a dedicated wpkey_live_... collector key. Secret
nskey_live_... API keys are rejected. Pixel events are treated as
funnel telemetry; verified Shopify webhooks remain authoritative for
revenue checkout/purchase Events.
Body
event_idstringrequiredevent_namestringproduct_viewedproduct_added_to_cartproduct_removed_from_cartrequiredcustomer_idstringemailstring<email>phonestringpropertiesobjectResponse
Event accepted, ignored, or dropped
Not authenticated
Validation failed
Authorization
bearerAuthRead an anonymous flow demo
A demo past its scan deadline (3 minutes) or its generation deadline (8 minutes) reads as failed.
Parameters
X-Flow-Demo-TokenstringrequiredheaderResponse
Current demo state
Start an anonymous brand scan for a flow demo
Creates a short-lived isolated demo workspace, not a visitor account, then scans the site and writes a flow for the goal. Requires a fresh Cloudflare Turnstile token for every attempt. Rate limited per IP (10 an hour, 20 a day); verified starts also count against a global daily cap.
Body
domainstringrequiredgoalstringrequiredturnstile_tokenstringrequiredSingle-use Turnstile token for the flow_demo_start action
Response
Scan started
Invalid or private website or goal (flow_demo_invalid), or a
missing or failed bot check (flow_demo_bot_check_failed).
Per-IP demo start limit reached
The demo is unavailable or its daily cap is spent
(flow_demo_unavailable).
Edit the scanned Brand Kit and regenerate the flow
Changed fields start one regeneration under a new revision; unchanged fields change nothing. Each demo has four generation attempts in total.
Body
fieldsobjectrequiredParameters
X-Flow-Demo-TokenstringrequiredheaderResponse
The demo after the edit
Expired or unscanned demo, or a field that is not an editable brand
field (flow_demo_invalid); no attempts left
(flow_demo_attempts_exhausted).
Retry a demo that failed during generation
Starts one regeneration under a new revision. Any other demo is returned unchanged. A demo that failed during the scan cannot be retried: start again.
Parameters
X-Flow-Demo-TokenstringrequiredheaderResponse
The demo after the retry
Expired demo or a failed scan (flow_demo_invalid); no attempts
left (flow_demo_attempts_exhausted).
Get guest-safe Flow Builder steps and triggers
Response
Flow editor schema restricted to guest-authorable actions
Get a canonical email template for guest editing
Returns one known system catalog template as concrete, validated editor JSON. Catalog theme markers are resolved before the response. The response contains no account-specific data and does not create a saved template.
Parameters
idstringrequiredpathrevisionstringqueryOpen only the design revision shown in a published gallery preview.
Response
Canonical catalog template
Resource not found
The requested preview revision is no longer current. The visitor can explicitly open the current version.
Get the email editor schema for guest editing
Returns the canonical component and theme schema used by the email editor.
Response
Email component schema
Create or update a public contact (website forms)
Public signup endpoint for website forms. Authenticate with a wpkey_live_… public key. Returns { ok: true } whether the contact is new or already subscribed; this preserves idempotency and avoids leaking which emails are on the list.
Use the brand's public key (wpkey_live_…). Secret keys (nskey_live_…) are rejected on this endpoint.
Body
emailstring<email>requiredSubscriber email address.
list_idintegerrequiredID of a contact list owned by the brand whose public key is presented.
first_namestring | nullOptional first name written to the contact.
last_namestring | nullOptional last name written to the contact.
phonestring | nullOptional E.164 phone number written to the SMS channel if provided.
sourcestring | nullOptional free-text label, e.g. "footer-form" or "/pricing", recorded against the signup.
dataobject | nullOptional bag of custom contact data. Reserved keys are silently dropped.
Response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get available plans
Response
Active plans
MCP
Model Context Protocol JSON-RPC endpoint and discovery
Probe the MCP OAuth endpoint
Unauthenticated probes receive the RFC 9728 protected-resource metadata
URL in WWW-Authenticate so OAuth clients can continue discovery.
Authenticated requests receive 405 Method Not Allowed because this
server does not offer a server-initiated event stream over GET. Use
POST /mcp for MCP Streamable HTTP requests.
Response
MCP authentication required
Authenticated GET is not supported by the MCP transport
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
MCP JSON-RPC endpoint
JSON-RPC endpoint for the Nitrosend MCP server. Read nitro://account,
nitro://config, or call nitro_get_status for bound account identity;
there is no per-tool account override argument.
Body
Response
JSON-RPC response
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Personal Agent Protocol discovery document
Personal Agent Protocol (Poppy) 1.0 discovery
(https://personalagentprotocol.org/docs/1.0/spec#3-discovery). Names the
MCP server, describes the mcp and send-approvals scopes, and lists
the Operations (version 3) and mailschema.org/map (version 1)
extensions. The MAP extension, defined at
https://mailschema.org/specification/poppy, maps Campaign Send Approval
0.1 to the nitro_send_approval MCP tool; it is listed only when the
serving origin is the MAP service origin. Poppy clients sign in through
the OAuth issuer named by /.well-known/oauth-protected-resource,
authenticating with private_key_jwt. Served only on the canonical API
origin and only while POPPY_ENABLED is on; otherwise 404.
Response
The discovery document
Poppy is off, or the request is not for the canonical API origin
Operator
Internal production support operations; requires an admin or staff API key
Make an existing account a partner
Requires a staff user. Grants the Affiliates tab (affiliate_center) and Client
Management (managed_clients). The account keeps its plan and billing is untouched.
Identify the account with exactly one of account_id, user_id or email.
Body
account_idintegeruser_idintegeremailstring<email>Response
Partner access enabled, or already enabled
Not authenticated
Not authorized
Resource not found
Partner access was revoked by an admin and is not re-granted
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
List the production customer-support queue
Requires an nskey_live_... API key owned by an admin or staff user. Browser JWTs are rejected.
Parameters
statusstringquerydue_onlybooleanfalsequeryaccount_idintegerquerybrand_idintegerquerypageinteger1querylimitinteger<= 10025queryResponse
Paginated support queue
Not authenticated
Not authorized
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get one production support case
Parameters
idintegerrequiredpathResponse
Support request, customer account, brand, and latest reply ledger state
Not authenticated
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Read bounded live diagnostics for a support case
Parameters
idintegerrequiredpathResponse
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Persist a versioned customer reply draft
Body
bodystringrequiredrunx_receipt_idstring | nullParameters
idintegerrequiredpathResponse
Draft persisted in the reply ledger
Bad request
Not authenticated
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Send one current versioned customer reply
Delivery is fail-closed and requires confirm: true; stale draft versions are rejected by the server ledger.
Body
thread_record_idintegerrequireddraft_versionintegerrequiredconfirmbooleanrequiredParameters
idintegerrequiredpathResponse
Reply delivered
Bad request
Not authenticated
Not authorized
Resource not found
Validation failed
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Set the persistent support-case disposition
Body
statusstringopenwaitingresolvedrequiredconfirmbooleantruerequiredExplicit confirmation of the disposition mutation.
follow_up_atstring<date-time>Required only for waiting.
Parameters
idintegerrequiredpathResponse
Updated support request
Bad request
Not authenticated
Not authorized
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Chat Sessions
List persisted chat sessions
Parameters
pageinteger1querylimitinteger<= 10025queryResponse
Paginated list of chat sessions
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Get a persisted chat session with ordered messages
Parameters
idintegerrequiredpathResponse
Chat session
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Close an active persisted chat session
A request from an embedded Shopify session closes only a session that session's install started; any other session answers 404.
Parameters
idintegerrequiredpathResponse
Closed chat session
Resource not found
Authorization
BearerAuthhttp (bearer)Authentication scheme depends on the route:
- Authenticated endpoints (
/v1/my/*) accept a server API key (nskey_live_...), a Nitrosend JWT, or a verified Shopify App Bridge ID token for an active embedded installation. API key is checked first. - Public website-form endpoints (
/v1/public/*) require a brand public key (wpkey_live_...). Secret keys (nskey_live_...) are rejected here so they can't be smuggled into browser code.
For accounts with multiple brands, include the X-Brand-SID header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include X-Account-ID to select
an accessible account.
Models
WorkspaceAttentionItem
objectkeystringrequiredtitlestringrequireddetailstringrequiredstatestringaction_requiredworkingrequiredblockingbooleanrequiredupdated_atstring<date-time>requiredtoWorkspaceRoute | nullrequiredactionstringrequiredhrefstringprogressobjectdismissiblebooleanchat_session_idintegerpriorityintegerAccount-wide restrictions use 0 and precede individual tasks.
recovery_actionsArray<object>Existing recovery actions for this restriction; opening one never approves or resumes sending.
WorkspaceActivityItem
objectidintegerrequiredsourcestringmcpnitrollmapirequiredtitlestringrequiredoutcomestringokincompleteacceptedstreameddeniederrorhttp_errorunknownrequiredclientstring | nullrequiredcreated_atstring<date-time>requiredtoWorkspaceRoute | nullrequiredOperatorSupportRequest
objectidintegerrequiredaccount_idintegerrequiredbrand_idintegerrequiredsubjectstringrequiredmessagestringrequiredstatusstringopenwaitingresolvedrequiredfollow_up_atstring<date-time> | nullresolved_atstring<date-time> | nulllast_replied_atstring<date-time> | nullcreated_atstring<date-time>requiredupdated_atstring<date-time>requiredOperatorSupportCase
objectsupport_requestOperatorSupportRequest & objectrequiredaccountobjectrequiredbrandobjectrequiredlatest_replyobject | nullgithub_issueobject | nullOperatorReplyDraft
objectstatusstringdraftedsentrequiredsupport_request_idintegerrequiredthread_record_idintegerrequireddraft_versionintegerrequireddraft_statestringterminal_outcomestring | nulllast_replied_atstring<date-time> | nullTimelineEntry
objectOne normalised, whitelisted entry in a contact's unified timeline.
idstringrequiredStable composite id, e.g. "event-123".
kindstringeventactivitylifecyclemessagerequiredtypestringrequiredEvent/activity/lifecycle type, e.g. checkout, opened, flow_exit.
titlestringrequiredHuman-readable label for the entry.
occurred_atstring<date-time>requiredmetaobjectrequiredDisplay-only extras (e.g. amount, resource_name). Flow exits include the flow name in resource_name and its exit_event. No internal fields.
EnterpriseRequestInput
objectmonthly_emailsinteger | string | nullEmails a month they expect to send, from 0 to 1,000,000,000, as a whole number or a string of up to 10 digits.
needsArray<string> | nullvolume_pricingdedicated_ipseats_or_domainssecurity_reviewinvoicingmigrationmessagestring | nullEnterpriseRequestReceipt
objectreceivedbooleanrequiredreplayedbooleanrequiredTrue when this is the member's request from earlier today.
requestobjectrequiredSafetyRecoveryAction
objecttypestringask_teamdomain_settingsrequiredlabelstringrequiredurlstringrequiredFor ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.
review_idintegerThe held case
promptstringThe staged request
SendRefusalDetail
objectPresent when the safety check refused the email. For content.image_unavailable and content.unreviewable it couldn't read the email, for reasons the sender can fix: no review is opened; change the email and send again. For content.vetting_review the email is held for review, and for content.vetting_denied it was blocked; how much either says depends on the account (some carry only the generic copy, or nothing more).
reason_codestringcontent.image_unavailablecontent.unreviewablecontent.vetting_reviewcontent.vetting_deniedhow_to_fixstringThe changes to make, in order, then how to send again. For a held or blocked email, how much is said depends on the account: some refusals carry only the generic copy.
categorystringThe kind of concern, when the account may be told it: unsolicited_bulk, impersonation or unsupported_authority (trusted accounts may also see an abuse label).
agent_promptstringThe reason and fix as one paragraph to paste to an agent. Names IDs only, never text from the email.
recovery_actionsArray<SafetyRecoveryAction>detailsobjectError
objectcapacity_recoveryDeliveryCapacityRecoveryInformational recovery at 80 percent used, exhaustion, or when a campaign exceeds remaining allowance. Never denies a send or promises that payment or verification bypasses safety. Actions come from the shared backend projection; only offer verification when new valid proof can improve standing. Capacity counters and usage_percent are present for the account's commercial allowance only; shared probation notices never disclose platform totals.
recovery_actionobjectContext-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.
codeintegerrequiredmessagestringrequirederrorbooleanrequirederror_codestring | nullOptional machine-readable error reason.
provisioning_idinteger | nullExisting provisioning row involved in a managed-account conflict.
retryablebooleanWhether retrying the same idempotent operation can succeed.
retry_atstring<date-time>Earliest recommended retry time for a retryable failure.
SignupPromoResult
objectappliedbooleanrequiredWhether the code was redeemed.
reasonstringappliedblanknot_foundnot_redeemableplan_not_foundpartner_access_revokedrequiredpartnerbooleanrequiredTrue when the code made the account a partner (Affiliates tab and Client Management). Partner codes never change the plan.
plan_grantedbooleanrequiredTrue only when a referral code granted a plan.
plan_pendingbooleanTrue when an optional partner plan offer is being applied after signup.
StaffPartnerGrantResult
objectstatusstringpartner_enabledalready_partnerrequiredmessagestringrequiredaccount_idintegerrequiredemailstring | nullplanstring | nullThe account's current plan slug, unchanged by this call.
commercial_tierstring | nullcapabilitiesArray<string>affiliate_centermanaged_clientsrequiredSignupVerificationRequired
objectstatusstringverification_requiredrequirederror_codestringverification_requirednext_actionstringverify_emailrequiredmessagestringrequirederrorbooleancodeintegerverification_expires_ininteger1800SignupSession
objectidintegerfirst_namestring | nulllast_namestring | nullemailstring<email>email_verified_atstring<date-time> | nullActual email proof time; legacy access does not fabricate proof.
unconfirmed_emailstring<email> | nullRequested email change awaiting proof. Continue signing in with email until confirmation.
signup_completed_atstring<date-time> | nullmobilestring | nullcountry_codestring | nulltime_zonestring | nulladminbooleanui_login_countintegerCapped three-state dashboard-login counter: 0 = the user has never logged into the app UI, 1 = the user is inside their first UI login, 2 = returning. Advances only on real dashboard logins (never on API key, MCP, or agent-connect authentication).
created_atstring<date-time>updated_atstring<date-time>metaobjectUser
objectidintegerfirst_namestring | nulllast_namestring | nullemailstring<email>email_verified_atstring<date-time> | nullActual email proof time; legacy access does not fabricate proof.
unconfirmed_emailstring<email> | nullRequested email change awaiting proof. Continue signing in with email until confirmation.
signup_completed_atstring<date-time> | nullmobilestring | nullcountry_codestring | nulltime_zonestring | nulladminbooleanui_login_countintegerCapped three-state dashboard-login counter: 0 = the user has never logged into the app UI, 1 = the user is inside their first UI login, 2 = returning. Advances only on real dashboard logins (never on API key, MCP, or agent-connect authentication).
created_atstring<date-time>updated_atstring<date-time>ManagedAccountLifecycleStatus
stringsetup is a claimed client on the unpaid Setup plan whose manager access is active; it is never reported as active until the client pays.
ManagedAccountLifecycleStatusFilter
stringManagedAccountProvisioning
objectidintegerrequiredexternal_refstringrequiredsourcestringdashboardpartner_apirequiredstatusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequiredsetup is a claimed client on the unpaid Setup plan whose manager access is active; it is never reported as active until the client pays.
permission_setstringoperator_v1requiredallowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequiredmanaged_accountobjectrequiredmanaged_on_setupbooleanrequiredThe client account is on Setup mode now, whatever the invitation's state. The agency builds and tests in it, and live email waits until the owner chooses a paid plan.
managed_plan_paidbooleanrequiredThe client account already has an active paid plan (for example one the agency bought), so the owner does not need to choose one to keep the agency's access.
ownerobjectrequiredinvitationobjectrequiredcreated_atstring<date-time>requiredupdated_atstring<date-time>requiredManagedAccountProvisioningCreated
objectidintegerrequiredexternal_refstringrequiredsourcestringdashboardpartner_apirequiredstatusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequiredsetup is a claimed client on the unpaid Setup plan whose manager access is active; it is never reported as active until the client pays.
permission_setstringoperator_v1requiredallowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequiredmanaged_accountobjectrequiredmanaged_on_setupbooleanrequiredThe client account is on Setup mode now, whatever the invitation's state. The agency builds and tests in it, and live email waits until the owner chooses a paid plan.
managed_plan_paidbooleanrequiredThe client account already has an active paid plan (for example one the agency bought), so the owner does not need to choose one to keep the agency's access.
ownerobjectrequiredinvitationobjectrequiredcreated_atstring<date-time>requiredupdated_atstring<date-time>requiredidempotent_replaybooleanrequiredAccountProvisioningCredential
objectidintegerrequirednamestringrequiredscopesArray<string>provisionmanagerequiredsecret_hintstringrequiredexpires_atstring<date-time>requiredlast_used_atstring<date-time> | nullrevoked_atstring<date-time> | nullcreated_atstring<date-time>requiredAccountProvisioningCredentialIssued
objectidintegerrequirednamestringrequiredscopesArray<string>provisionmanagerequiredsecret_hintstringrequiredexpires_atstring<date-time>requiredlast_used_atstring<date-time> | nullrevoked_atstring<date-time> | nullcreated_atstring<date-time>requiredsecretstringrequiredwrite onlyOne-time nspk_live_ credential secret.
AccountManagementCredential
objectidintegerrequiredaccount_management_grant_idintegerrequirednamestringrequiredpermission_setstringoperator_v1requiredsecret_hintstringrequiredexpires_atstring<date-time>requiredlast_used_atstring<date-time> | nullrevoked_atstring<date-time> | nullcreated_atstring<date-time>requiredbrandobjectrequiredAccountManagementCredentialIssued
objectidintegerrequiredaccount_management_grant_idintegerrequirednamestringrequiredpermission_setstringoperator_v1requiredsecret_hintstringrequiredexpires_atstring<date-time>requiredlast_used_atstring<date-time> | nullrevoked_atstring<date-time> | nullcreated_atstring<date-time>requiredbrandobjectrequiredsecretstringrequiredwrite onlyOne-time nsmc_live_ credential secret.
ManagedAccountClaimInspection
objectmanagerobjectrequiredmanaged_accountobjectrequiredowner_emailstringrequiredMasked owner address
expires_atstring<date-time>requiredauthenticationstringrequiredManagedAccountClaimCompletion
objectclaimedbooleanrequiredstatusstringpayment_requiredactivemanager_disabledrequiredThe agency's management access. active on Setup mode does not mean paid; read payment_required.
payment_requiredbooleanrequiredThe owner still has to choose a paid plan before live email. True on Setup mode, even though status is active, and whenever no paid plan is active; false when a paid plan is active, such as one the agency already bought.
managed_on_setupbooleanrequiredThe client account is on Setup mode.
managed_accountobjectrequiredAccount
objectidintegernamestring | nullavatarstring | nullSigned blob ID
bannerstring | nullSigned blob ID
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriseThe current plan's tier. setup is Setup mode, the hidden plan an agency and every client account it creates build and test on before a paid plan turns on live email.
safe_mode_enabledbooleanaccessAccountAccessbillingAccountBilling | DelegatedAccountBillingOwners, admins and members get the full projection. An agency operator working in a client account it manages, or a management credential, gets the delegated projection: enough to choose and pay for the client's first plan from Setup mode, with no usage, funding, spend cap, payment or invoice details.
teamobjectPresent for direct access and omitted from delegated account projections.
created_atstring<date-time>updated_atstring<date-time>AccountBilling
objectBilling for direct access (owners, admins and members, and their own credentials).
access_policystring | nullfree_allowedpaid_requiredrequiredplan_namestring | nullplanPlan | nullspend_cap_monthly_centsinteger | null>= 0compedbooleanoverageobjectentitlementsBillingEntitlementsresourcesobjectfundingobjectrequiredprovider_routeobjectrequiredremovable_brandingbooleanWhether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).
outstanding_invoiceobject | nullPresent while sending is paused because the account has an unpaid invoice; null otherwise. Owners and admins can pay it through GET /v1/my/invoices/{id}/payment.
brandsobjectrequiredPer-account brand-count headroom. Usage for email, SMS, and AI remains pooled at the account level; only brand count is capped here. A limit of 0 with unlimited=true means unlimited brands.
domainsobjectAccount-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.
lifetimeobjectDelegatedAccountBilling
objectBilling for an agency operator working in a client account it manages (delegated access): the plan, its status, the tier, the access policy and the billing route, which is what choosing and paying for the client's first plan from Setup mode needs. Usage, funding, spend cap, payment and invoice details stay with the account's owner and admins.
access_policystring | nullfree_allowedpaid_requiredrequiredplanPlan | nullrequiredsubscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequiredcommercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequiredprovider_routeobjectrequiredSendingPause
objectWhat the owner of a suspended account is told. A deliverability pause names the metric and the fix (reason, what_to_do). Any other suspension is opaque and carries no reason. Recovery actions reach the existing support channel.
sending_pausedbooleantruerequiredreasonstringcritical_bounce_ratecritical_complaint_ratePresent only for an explained deliverability pause.
occurred_atstring<date-time>requiredheadlinestringrequireddetailstringrequiredwhat_to_doArray<string>Present only for an explained deliverability pause.
request_reviewstringrequiredThe instruction an agent relays to the owner.
recovery_actionsArray<object>requiredAccountResourceUsage
objectusedintegerrequiredallowanceinteger | nullrequiredremaininginteger | nullrequiredoverage_ratenumberrequiredmodestringbudgetmonthlyunlimitedrequiredbudgetinteger | nullrequiredbudget_usedintegerrequiredAccountAccess
objectsourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequireddelegatedbooleanrequiredmanager_account_idintegermanager_account_namestring | nullmanagement_grant_idintegerpermission_setstringoperator_v1credential_typestringmanagementAccountManagementGrant
objectidintegerrequiredstatusstringpendingactiverevokedreleasedrequiredpermission_setstringoperator_v1requiredmanager_accountobjectrequiredrequested_atstring<date-time>requiredactivated_atstring<date-time> | nullrevoked_atstring<date-time> | nullreleased_atstring<date-time> | nullAccountManagementGrantCommand
objectmanagement_grant_idintegerrequiredExact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.
AccountTeam
objectaccountAccountmembershipsArray<AccountMembership>invitesArray<AccountInvite>accessible_accountsArray<Account>AccountMembership
objectidintegerrolestringmemberadminowneruser_idintegeremailstring<email>namestring | nullcreated_atstring<date-time>updated_atstring<date-time>AccountInvite
objectidintegeraccount_idintegeremailstring<email>rolestringmemberadmintokenstringstatusstringpendingacceptedrevokedexpiredaccepted_atstring<date-time> | nullrevoked_atstring<date-time> | nullexpires_atstring<date-time> | nullcreated_atstring<date-time>updated_atstring<date-time>Subscription
objectidintegerplan_idintegerplan_namestring | nullCurrent package name. Historical purchase labels are retained in billing records.
billing_providerstring | nullshopifystripestripe_projectsvercelawssource_billing_providerstring | nullshopifystripestripe_projectsvercelawsbilling_migration_requiredbooleanmanage_urlstring<uri> | nullspend_cap_monthly_centsinteger | null>= 0Merchant-selected monthly cap for metered usage charges.
shopify_usage_meteredbooleanWhether the active Shopify plan has at least one configured usage meter.
statusstringpendingactiveinactivecanceledfree_tierintervalstringmonthyearweekdaycurrencystringsubtotal_centsintegertax_centsintegertotal_centsintegerbase_price_centsintegerdiscount_centsintegerPer-period Stripe discount in cents (0 when none).
next_payment_centsintegerAmount billed next period
discount_end_atstring<date-time> | nullWhen the discount stops (null for forever/once or no discount).
activatedbooleanentitlementsBillingEntitlementsAgentInboxEntitlement
objectenabledbooleanrequiredmax_inboxesinteger | null>= 0requiredAccount-wide exact-inbox capacity. Null means contract-defined unlimited capacity.
included_inboxesinteger | null>= 0Effective included allowance
grandfathered_inboxesinteger>= 0purchased_inboxesinteger>= 0Confirmed paid units only.
coexistence_inboxesinteger>= 0Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.
inbound_messages_includedinteger | null>= 0requiredinbound_messages_meteredbooleanrequiredinbound_message_overage_rate_centsstringrequiredmax_inbound_domainsinteger | null>= 0requiredmax_apex_domainsinteger | null>= 0requiredapex_mxbooleanrequiredlegacy_forwardingbooleanrequiredcatch_allbooleanrequiredretention_daysinteger | null>= 0requiredadvanced_queue_controlsbooleanrequiredSubscriptionCreateRequest
objectplan_idintegerrequiredstripe_tokenstring | nullStripe card token for paid-plan creation.
coupon_codestring | nullCustomer-entered Stripe promotion code or coupon ID. Refused on an agency operator's purchase for a client account.
DelegatedSubscription
objectWhat an agency operator working in a client account it manages sees of its subscription: the plan, its status and the billing route, which is what choosing and paying for the first plan from Setup mode needs. Payment, invoice, discount, spend cap and renewal details stay with the account's owner and admins.
idintegerrequiredplan_idintegerrequiredplan_namestring | nullrequiredstatusstringpendingactiveinactivecanceledfree_tierrequiredintervalstringmonthyearweekdayrequiredcurrencystringrequiredactivatedbooleanrequiredbase_price_centsintegerrequiredbilling_providerstring | nullshopifystripestripe_projectsvercelawsrequiredsource_billing_providerstring | nullshopifystripestripe_projectsvercelawsrequiredbilling_routeobjectrequiredplanPlan | nullrequiredFundingPurchaseCreateRequest
objectamount_centsinteger>= 1requiredInteger service value in minor currency units.
currencystringinstrumentstringstripe_checkoutshopify_one_timeOptional hosted funding instrument. Omit to use the account default.
paid_action_intent_idstring | nullOptional opaque continuation bound to this funding purchase.
FundingInstrument
objectinstrumentstringstripe_checkoutshopify_one_timerequiredproviderstringstripeshopifyrequiredmodestringhosted_approvalrequiredavailablebooleanrequiredreasonstring | nullFundingUrlApproval
objectkindstringurlrequiredproviderstringstripeshopifyrequiredurlstring<uri>requiredtargetstringselftoprequiredFundingChallengeApproval
objectkindstringchallengerequiredinstrumentstringrequiredprotocolstringrequiredchallengestringrequiredexpires_atstring<date-time> | nullFundingApproval
objectkindstringurlrequiredproviderstringstripeshopifyrequiredurlstring<uri>requiredtargetstringselftoprequiredkindstringchallengerequiredinstrumentstringrequiredprotocolstringrequiredchallengestringrequiredexpires_atstring<date-time> | nullFundingPurchase
objectidintegerrequiredpaid_action_intent_idstring | nullproviderstringstripeshopifyrequiredinstrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequiredstatusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequiredcurrencystringrequiredrequested_centsinteger>= 1requiredrequested_displaystringcheckout_urlstring<uri> | nullapprovalFundingUrlApproval | FundingChallengeApproval | nullexpires_atstring<date-time> | nullcredited_centsinteger>= 0requiredreversed_centsinteger>= 0requiredcreated_atstring<date-time>requiredupdated_atstring<date-time>requiredFundingPurchaseCapability
objectavailablebooleanrequiredstatestringrequiredreasonstring | nulldefault_instrumentstring | nullstripe_checkoutshopify_one_timecurrencystringrequiredminimum_centsinteger | nullmaximum_centsinteger | nullpreset_centsArray<integer>requiredFundingStatus
objectstatestringrequiredapplies_tostringprepaid_featuresrequiredsubscription_gatebooleanrequiredcurrencystringrequiredavailable_centsintegerrequiredreserved_centsintegerrequireddeficit_centsintegerrequiredpending_purchaseFundingPurchase | nullSubscriptionChangeRequest
objectplan_idintegerrequiredcoupon_codestring | nullCustomer-entered Stripe promotion code or coupon ID.
SubscriptionCouponPreviewRequest
objectplan_idintegerrequiredcoupon_codestringrequiredCustomer-entered Stripe promotion code or coupon ID.
SubscriptionCouponPreview
objectcodestringrequireddiscount_labelstringrequireddiscount_centsintegerrequiredsubtotal_centsintegerrequiredtax_centsintegerrequiredtotal_centsintegerrequiredtotal_after_discount_centsintegerrequiredcurrencystringrequiredOAuthPopupAccount
objectidintegerrequirednamestringrequiredaccessAccountAccesscan_managebooleanhas_campaignbooleanWhether the account has made any campaign. This alone does not determine onboarding eligibility.
setup_brandobject | nullOptional setup for a fresh, unconfigured workspace, visible only to a direct manager. Start setup through the existing brand endpoints; OAuth need not wait for the scan.
needs_subscribebooleanrequiredplansArray<Plan>Offers available through this account's provider, including retained Free terms when eligible.
OAuthPopupPlan
objectidintegerrequirednamestringrequiredslugstringrequiredbase_price_centsintegerrequiredintervalstring | nulltier_groupstringOAuthPopupContext
objectapplication_namestring | nullemailstringThe signed-in person's address, where an agent's first test goes.
stripe_publishable_keystring | nullOAuthPopupSubscribeRequest
objectplan_idintegerrequiredaccount_idinteger | nullstripe_tokenstring | nullFirstTouchAttributionContext
objectOptional first-touch attribution captured by the client for a new-account signup. Send URLs without query strings. UTM values have control characters removed and surrounding whitespace stripped, and are capped at 100 characters server-side. Click identifiers are accepted only as strings: surrounding whitespace is stripped, then the whole value must be 1-255 ASCII letters, digits, underscores, periods or hyphens; an invalid or oversized identifier is omitted, never truncated, without rejecting the signup. Values are persisted only for a genuinely new account and never overwrite an earlier first touch.
landing_urlstring | nullreferrer_urlstring | nullcaptured_atstring<date-time> | nullutm_sourcestring | nullutm_mediumstring | nullutm_campaignstring | nullutm_contentstring | nullutm_termstring | nullfbclidstring | nullMeta click identifier (fbclid) from the first touch, subject to the click-identifier rules above.
ttclidstring | nullTikTok click identifier (ttclid) from the first touch, subject to the click-identifier rules above.
OAuthLaunchRequest
objectproviderstringgoogle_oauth2githubrequiredauth_intentstringappagentappauth_stepstringloginsignuploginresume_urlstring<uri> | nullRequired when auth_intent=agent; must point to the frontend /oauth/connect route.
invite_tokenstring | nullreferral_codestring | nullrewardful_referral_idstring | nullattribution_contextFirstTouchAttributionContextOptional first-touch attribution captured by the client for a new-account signup. Send URLs without query strings. UTM values have control characters removed and surrounding whitespace stripped, and are capped at 100 characters server-side. Click identifiers are accepted only as strings: surrounding whitespace is stripped, then the whole value must be 1-255 ASCII letters, digits, underscores, periods or hyphens; an invalid or oversized identifier is omitted, never truncated, without rejecting the signup. Values are persisted only for a genuinely new account and never overwrite an earlier first touch.
signup_intentSignupIntent | nullagencyOptional. agency marks a signup that came from the agencies page; a new account created with it becomes a partner (Affiliates tab, client management, a personal Rewardful campaign) unless the signup is held for review. Any other value is ignored and the signup proceeds normally.
SignupIntent
stringOptional. agency marks a signup that came from the agencies page; a new account created with it becomes a partner (Affiliates tab, client management, a personal Rewardful campaign) unless the signup is held for review. Any other value is ignored and the signup proceeds normally.
Brand
objectidintegersidstringread onlyPublic secure identifier (non-sequential)
account_idintegerbrand_colorstring | nulltext_colorstring | nullbg_colorstring | nullradiusinteger | null[0, 64]spacing_densitystring | nullcompactnormalspaciousfont_headingstring | nullfont_bodystring | nullheading_sizeinteger | null[12, 48]body_sizeinteger | null[12, 20]brand_documentstring | nullcompany_descriptionstring | nulldefault_headerobject | nulldefault_themeobject | nullphysical_addressstring | nullcompany_namestring | nullsource_urlstring | nulllast_scraped_atstring<date-time> | nulllinksArray<object> | nulllogostring | nullLogo URL
completebooleanTrue when brand_color and company_name are set
email_from_namestring | nullemail_from_emailstring | nullemail_reply_tostring | nullfrom_email_domain_statusstringblankverifiedunverifiedAuthorization state of the configured visible From address.
effective_from_emailstring<email> | nullread onlyeffective_reply_tostring<email> | nullread onlyeffective_sending_domainstring | nullread onlyeffective_source_emailstring<email> | nullread onlysender_configuredbooleanread onlyemail_view_onlinebooleanDefault-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.
email_view_online_placementstringtopfooterWhere the view-in-browser link goes: at the top of the email (default), or beside the Unsubscribe link in its footer. The link is only added once the campaign's web copy exists.
email_track_opensbooleanDefault-on brand setting. When false, this brand's emails carry no open-tracking pixel and opens from mail already sent are not recorded.
email_track_clicksbooleanDefault-on brand setting. When false, this brand's links are not rewritten and clicks from mail already sent are not recorded; delivered links keep working.
test_email_recipientsArray<string>onboarding_stateobjectJSONB — keys are step names, values are completion metadata
onboardingobjectdomain_verifiedbooleancan_sendbooleanbrand_subdomainBrandSubdomain | nullbyo_routingobjectWarns when the brand has connected its own (BYO) email provider but verified sending domains still route through Nitrosend's hosted provider. Read-only; never blocks a send. mismatch is false (and message null) when all is well.
subscribed_contacts_countintegerCount of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.
logo_urlstring<uri> | nullread onlylogo_tonestring | nulllightdarkread onlyMeasured from the logo. A light mark on transparent gets a header band in emails.
logo_aspectnumber | nullread onlyThe logo's width over its height. Emails fit the logo to one header height.
screenshot_urlstring<uri> | nullread onlycapabilitiesobjectsms_provisionedbooleanread onlycreated_atstring<date-time>updated_atstring<date-time>BrandSubdomain
objectnamespace_statusstringunreservedactivereplacement_pendingretiringretiredrequiredstatusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequiredreadybooleanrequiredselectedbooleanpreparation_requiredbooleanrequiredfrom_emailstring<email>fqdnstringapexstringlocal_partstringlocal_part_editablebooleanfqdn_changeablebooleanWhether the current hosted address offers a rename. The write still enforces pending work and claim allowances.
suggested_subdomainstring | nullCandidate offered while the brand has no namespace (namespace_status: unreserved): derived from the company name, or from the account owner while the Brand Kit is incomplete. Absent once a name is reserved, because an allocated name never changes, and absent when nothing safe can be derived.
messagestringOnly with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.
AudienceReachFit
objectplan_idintegerrequiredslugstringrequirednamestringrequiredtier_groupstringrequireddaily_capinteger | nullRecipients per 24 hours at the account's sending standing; null when unlimited
capacityinteger | nullEmails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited
days_to_reachinteger | nullDays until everyone has been reached once; null when the month cannot hold the send
coversbooleanrequiredWhether one full send to the audience fits within the month
AudienceReach
objectaudienceintegerrequiredcohortstringrequiredThe account's deliverability cohort the daily caps are read at
currentAudienceReachFit | nullThe current plan; null when the account has no subscription
recommendedAudienceReachFit | nullThe cheapest listed plan above the current one whose first month holds the send; null when the current plan covers it or no listed plan would
coveredbooleanrequiredWhether the current plan covers a full send
summarystring | nullThe one sentence every surface shows; null when covered
HostedSenderAvailability
objectsubdomainstringrequiredThe normalised label that would be reserved (or the input when unsafe)
fqdnstring | nullavailablebooleanrequiredreasonstring | nulltakenunsafereservedlocal_part_invalidWhy the address is unavailable; null when available
local_partstring | nullThe normalised local part that would be reserved (the allocator's default when none was given), or the input when it is invalid.
from_emailstring | nullThe exact address that would be reserved; null when unavailable for a policy reason
BrandDeletionSafetyImpact
objectcontactsinteger>= 0requiredcampaignsinteger>= 0requiredflowsinteger>= 0requiredtemplatesinteger>= 0requireddomainsinteger>= 0requiredmessagesinteger>= 0requiredBrandDeletionSafetyActiveSends
objectqueued_messagesinteger>= 0requiredactive_campaignsinteger>= 0requiredScheduled or live campaigns.
BrandDeletionSafety
objectcan_deletebooleanrequiredTrue when no force confirmation is required.
requires_forcebooleanrequiredTrue when active sends require force=true to delete.
AffiliateCenterPayload
objectenrolledbooleanrequiredWhether the account is linked to a Rewardful affiliate.
availablebooleanrequiredWhether live affiliate data or setup is currently available.
statestring | nullactivepausedunavailablesetup_statusstring | nullpendingneeds_detailsunavailablePresent only while an entitled, unlinked account is being reconciled.
statsobjectearningsobjectBrandWebsiteInput
objecturlstringrequiredReal business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.
BrandScanAdmission
objectstatusstringscanningscrapingrequiredurlstringrequiredscan_idstringrequiredidempotent_replaybooleanBrandScanStatus
objectstatusstringscanningcompletedfailedunknownrequiredscan_idstring | nullrequiredkindstringwebsitekiturlstringerrorstringpreviewobjectSetupCenterPayload
objectnext_actionsArray<object>Read-only onboarding recommendations and requirements. Blocking is scoped to the stated operation; this list never authorizes delivery. Custom-domain connection is optional when a provided sender is ready.
sectionsobjectprogressobjectCounts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.
seenbooleandismissedbooleancompletebooleanestablishedbooleanTrue once real accepted email history proves the brand has sent. Drafts, owner tests and operator proof are not activation. Current DNS health and recent analytics cannot reset this state. Independent of complete — an established brand may still carry incomplete cards it has chosen to skip. Clients use it to retire setup nudges.
welcome_emailobject | nullThe welcome email Nitrosend writes in the brand and puts in the owner's inbox once the brand has a Brand Kit of its own. A preview, not the brand's first send; the draft is kept for the brand to reuse. Null until it starts.
suggested_sitestring | nullA website the setup screen offers in its website box until the brand has a site of its own: the signup's work email domain, when it is a live site. Never scanned until the person asks.
sender_choicestring | nullownhostedWho a first real send comes from, once asked.
contact_sourceobject | nullThe mail tools the last scan found evidence of on the brand's site.
suggested_addressobject | nullA postal address the last scan found on the brand's own site, offered while the brand has no physical_address. It is never saved by the scan: save it as physical_address only after the person confirms it.
first_kitbooleanread onlyWhether a website read now saves itself as this brand's first Brand Kit. Once it's false, a preview waits for an explicit apply.
can_email_sign_in_linkbooleanread onlyPresent on authenticated UI snapshots. Whether this requester is the fresh account owner eligible to request the saved draft link; the command rechecks authorization and draft ownership.
current_scanobject | nullThe current admitted source reference and bounded progress. Cache expiry is unknown progress, not permission to apply a scan. Applied is a durable fact recorded on this exact source reference after its save; timestamps or cache entries for other attempts never establish it.
SetupCenterCard
objectidstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdnsThe setup steps are brand_kit_scan, import_subscribers and first_email, the brand's first real send to its contacts (required, counted in progress), and connect_agent (recommended). dns is not a step: it reports whether sending still needs an address set up.
completebooleanacknowledgedbooleanacknowledged_atstring<date-time> | nullclientstring | nullconnect_agent only: the agent that connected first, as the API names clients (for example Claude Code).
clientsArray<string>connect_agent only: the agents connected now, one per live MCP connection, by the same names. Agents the API cannot name are left out.
FieldCatalog
objectidintegerrequiredkeystringrequiredDot-separated field key. Typed contact columns use the bare column name
(e.g. email, first_name). JSONB data keys are prefixed with data.
(e.g. data.plan, data.apollo.title, data.hubspot.company, data.tags).
categorystringcontactcustomenrichmentengagementtagrequiredDerived from the key namespace.
contact— typed column on the contacts tabletag—data.tagsarrayenrichment— reserved enrichment namespaces such asdata.apollo.*,data.pdl.*,data.attio.*,data.hubspot.*,data.stripe.*,data.shopify.*, and deriveddata.nitro.*custom— any otherdata.*keyengagement— future engagement traits (reserved)
field_typestringstringnumberbooleandateenumrequiredInferred from the first observed value; pinned and never flipped.
presentation_typestringtextnumbercurrencypercentdatedatetimebooleanenumrequiredShared presentation contract used by fact displays and generated merge tags.
presentation_optionsobjectrequiredProvider-supplied formatting metadata such as decimal precision, currency-code field path, unit scale, or percentage multiplier.
labelstringrequiredHuman-readable label. Defaults to a humanised version of the key.
display_labelstringSource-qualified field label suitable for display.
source_keystring | nullsource_namestring | nullobject_labelstring | nullsource_field_labelstring | nullmerge_tagstring | nullReady-to-insert merge tag for a scalar custom or projected integration field. Typed fields include the deterministic presentation filter used by preview, test, and delivery rendering.
promotedbooleanrequiredWhether this field is pinned as a default column in the contacts grid.
fill_ratestring | nullPercentage of contacts that have a non-null value for this field. Computed asynchronously; may be null if the refresh job has not run yet.
75.0fill_rate_refreshed_atstring<date-time> | nullWhen fill_rate was last computed.
created_atstring<date-time>updated_atstring<date-time>DeliveryCapacity
objectsourcestringplanoperator_overridewindow_secondsintegerstatusstringknownunlimitednot_applicableunknowndegradedrequiredlimitinteger | null>= 0requiredreservedinteger | null>= 0requiredacceptedinteger | null>= 0requiredprovider_unknowninteger | null>= 0requiredremaininginteger | null>= 0requiredDeliveryPacingScope
objecttypestringrequiredkeystringstatusstringreadydeferredrequirednext_dispatch_atstring<date-time>minimum_interval_secondsnumber>= 0requiredbaseline_rate_per_secondnumber>= 0effective_rate_per_secondnumber>= 0cooldown_reasonstringcooldown_untilstring<date-time>feedback_epochinteger>= 0requiredDeliveryPacingState
objectstatusstringreadydeferredrequiredpolicy_versionstringrequiredqueued_quantityinteger>= 0next_dispatch_atstring<date-time>initial_bulk_observationobjectDeliveryStatusIssue
objectcontrolstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacityrequiredreason_codestringsending_pausedbrand_unavailablesender_not_readysending_capacity_reachedsignup_sending_capacity_reacheddelivery_evidence_pendingrequiredretryablebooleanrequiredretry_atstring<date-time>DeliveryStatus
objectassessment_scopestringrequiredadmission_statusstringalloweddeferreddeniedrequiredsending_pauseSendingPauseWhat the owner of a suspended account is told. A deliverability pause names the metric and the fix (reason, what_to_do). Any other suspension is opaque and carries no reason. Recovery actions reach the existing support channel.
capacity_recoveryDeliveryCapacityRecoveryInformational recovery at 80 percent used, exhaustion, or when a campaign exceeds remaining allowance. Never denies a send or promises that payment or verification bypasses safety. Actions come from the shared backend projection; only offer verification when new valid proof can improve standing. Capacity counters and usage_percent are present for the account's commercial allowance only; shared probation notices never disclose platform totals.
blocking_controlstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacityreason_codestringretry_atstring<date-time>observed_atstring<date-time>requiredCampaignVersionInput
objectsubjectstringrequiredgeneration_event_idintegerFrom a suggested line in readiness versions.lines.
candidate_locatorstringFrom a suggested line in readiness versions.lines.
CampaignWinnerInput
objectSend the versions to a test part of the list, then the winning version to the rest after the wait. Omit to split everyone. When nothing clearly wins, the rest gets the campaign's own subject line.
wait_hoursinteger248244measurestringopensclicksopensSubjectVersionOffer
objectSubject line versions for this campaign's audience. Read only.
eligiblebooleanaudience_countinteger | nullmax_versionsintegerwait_hoursArray<integer>statusstringnonewritingreadyunavailablephasestringcheckingWhile writing: the lines are written and their checks have begun. Absent before that.
reasonstringlinesArray<object>Suggested alternatives for the current content.
CampaignExperiment
objectThe test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.
idintegerrecipientsintegermodestringsplitwinnerstatestringrunningawaiting_winnersending_winnercompletestoppedmeasurestringopensclicksstop_reasonstringwait_hoursintegerdecide_atstring<date-time>decided_atstring<date-time>winner_sentintegerversionsArray<object>verdictobjectDeliveryReviewBudgetStatus
objectRead-only account allowance for potentially reviewable new email content. Informational only; it neither authorizes delivery nor blocks approval. Non-email readiness omits this property. Remaining allowance and reset times are omitted when unavailable or not applicable. Exhaustion does not imply that cached content or exempt workloads cannot be sent.
statusstringavailableexhaustednot_applicableunavailablerequiredassessment_scopestringrequiredchannelstringrequiredobserved_atstring<date-time>requiredmessagestringrequirednotestringrequiredreason_codestringretry_atstring<date-time>UTC release of the blocking calendar allowance; present when exhausted.
remainingobjectresets_atobjectDeliveryCapacityRecovery
objectInformational recovery at 80 percent used, exhaustion, or when a campaign exceeds remaining allowance. Never denies a send or promises that payment or verification bypasses safety. Actions come from the shared backend projection; only offer verification when new valid proof can improve standing. Capacity counters and usage_percent are present for the account's commercial allowance only; shared probation notices never disclose platform totals.
statestringapproachingreachedcampaign_exceeds_remainingrequiredreason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequiredblocking_controlstringcommercial_capacityshared_abuse_capacityrequiredusage_percentinteger[0, 100]requested_quantityinteger>= 0labelstringrequireddetailstringrequiredcapacityDeliveryCapacityupgrade_urlstring<uri>Shareable account-specific plan link. Authentication and billing permissions still apply.
retry_atstring<date-time>Recorded retry time, not a guarantee that delivery completes then.
recovery_actionDeliveryCapacityRecoveryActionowner_actionDeliveryCapacityRecoveryActionDeliveryCapacityRecoveryAction
objecttypestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequiredlabelstringrequireddetailstringurlstring<uri>requiredrequired_rolestringValidationAudience
objectlead_idsArray<integer>Explicit Lead selection in the current Brand. Does not create marketing Contacts or require a discovery search.
contact_channel_idsArray<integer>contact_idsArray<integer>list_idintegersegment_idintegerall_contactsbooleanAll email channels in the current Brand, subject to the 100000-candidate operation bound.
quote_digeststringPass the reviewed quote digest when creating an operation. A changed address set, eligibility or price returns 409 validation_quote_changed without holding funds. Omit only when intentionally authorizing the current audience at the current price.
ValidationOperationCounts
objectcandidate_countinteger>= 0requireddeduplicated_countinteger>= 0requiredcached_countinteger>= 0requiredineligible_countinteger>= 0requiredeligible_countinteger>= 0requiredpending_countinteger>= 0executing_countinteger>= 0billable_countinteger>= 0not_billable_countinteger>= 0provider_unknown_countinteger>= 0failed_countinteger>= 0ValidationOperationPricing
objectprice_book_versionstringrequiredunit_rate_centsstringrequiredincluded_quantityinteger>= 0maximum_charge_centsinteger>= 0requiredcommitted_centsinteger>= 0released_centsinteger>= 0currencystringrequiredquote_digeststringexpires_atstring<date-time>requiredexecution_deadline_atstring<date-time> | nullValidationOperationFunding
objectroutestringrequiredavailablebooleanrequiredreasonstringusage_event_idintegerstatestringneeds_fundingheldcommittedreleasedrecoveryobjectValidationOperationQuote
objectstatusstringquotedneeds_fundingrequiredsource_kindstringcontact_channelcontactlistsegmentall_contactsleadrequiredquote_digeststringrequiredmutationbooleanrequiredValidationOperation
objectoperation_idstringrequiredstatusstringrequestedquotedheldexecutingpartially_committedcommittedreleasedneeds_fundingfailedrequiredsource_kindstringcontact_channelcontactlistsegmentall_contactsleadrequireditem_detailobjectrequiredresultsobjectPer-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.
unconfirmedobjectUnknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.
failure_codestringstarted_atstring<date-time>completed_atstring<date-time>next_actionstringValidationOperationItem
objectidintegerrequiredcontact_channel_idinteger | nulllead_idinteger | nullemailstring<email>Current address only if it still matches the retained verification identity
provider_observed_atstring<date-time> | nullstatusstringpendingexecutingbillablenot_billableprovider_unknownfailedrequiredbillablebooleanproviderstringnative_statusstringverdictstringfailure_codestringresult_referenceobjectcompleted_atstring<date-time>ContactEnrichmentQuote
objectquote_digeststringselected_countintegerrequiredalready_current_countintegerrequiredreusable_countintegerrequiredprovider_required_countintegerrequiredmaximum_billable_outcomesintegerrequiredresourcestringcontact_profile_enrichmentunit_rate_centsstringrequiredmaximum_charge_centsintegerrequiredcurrencystringUSDrequiredprice_book_versionstringrequiredavailablebooleanrequiredreasonstring | nullSpendProjection
objectschemastringrequiredstatusstringreadyneeds_fundingpayment_pendingblockedunavailablerequiredroutestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequiredcurrencystringrequiredmaximum_charge_centsinteger>= 0requiredbalanceSpendBalancefundingobjectrequiredCanonical account funding projection from Billing::Funding::Presenter.
PaidActionIntentCreate
objectadapter_keystringrequiredadapter_versionstringrequiredoperation_idempotency_keystringrequiredstate_payloadobjectrequiredAdapter-owned state, validated and encrypted before persistence.
PaidActionIntent
objectidstringrequiredOpaque public continuation identifier.
schemastringrequiredstatusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequiredadapterobjectrequiredoperation_idempotency_keystringrequiredoriginal_quote_fingerprintstringrequiredcurrent_quote_fingerprintstringquote_changedbooleanstate_payloadobjectquoteobjectexpires_atstring<date-time>requiredconsumed_atstring<date-time> | nullcancelled_atstring<date-time> | nullSpendBalance
objectavailable_centsintegerrequiredreserved_centsinteger>= 0requiredshortfall_centsinteger>= 0requiredSpendRecoveryAction
objecttypestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailablereasonstringoperationstringadd_fundsurlstring<uri>purchase_idintegershortfall_centsinteger>= 0minimum_centsinteger>= 0maximum_centsinteger>= 0recommended_centsinteger>= 0preset_centsArray<integer>ContactEnrichmentFundingRequired
objectcodestringrequiredmessagestringrequirederrorbooleanrequirederror_codestringrequiredcurrencystringrequiredrequired_centsinteger>= 0requiredavailable_centsintegerrequiredreserved_centsinteger>= 0requiredshortfall_centsinteger>= 0requiredfundingobjectrequiredrecovery_actionobjectrequiredContactEnrichmentDispatch
objectselected_countintegerrequiredqueued_countintegerrequiredalready_current_countintegerrequiredreusable_countintegerrequiredprovider_required_countintegerrequiredmaximum_charge_centsintegerrequiredcurrencystringUSDrequiredprice_book_versionstringrequiredidempotent_replaybooleanrequiredContact
objectidintegerbrand_idinteger | nulluuidstring<uuid>first_namestring | nulllast_namestring | nullsourcestring | nullcountry_codestring | nullflag_emojistring | nullUnicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.
dataobjectCustom key-value data. The reserved key tags holds an array of
string labels used for segmentation and targeting. Reserved enrichment
namespaces such as apollo, pdl, attio, hubspot, stripe,
shopify, and derived nitro may appear when integrations or
enrichment jobs write source-scoped data.
{
"tags": [
"vip",
"newsletter"
],
"plan": "pro"
}subscribed_phonebooleansubscribed_emailbooleanemailstring<email> | nullConvenience value for the preferred email channel. Full channel detail remains in channels[].
subscribedobjectDenormalized subscription summary by channel family.
verification_statusstringverifiedsuppressedunverifiedverification_resultstring | nullvalidinvaliddisposablecatchallunknownnullNewest list-verification result for the contact's email; null when never checked.
enrichment_statusstringenrichednot_enrichedmailbox_providerstringgmailappleoutlookcorporateunknownDerived mailbox provider for the contact's primary email domain. Known consumer domains map to gmail, apple, or outlook; any other valid email domain maps to corporate; unknown means no email is present.
list_idsArray<integer>last_interacted_atstring<date-time> | nullcreated_atstring<date-time>updated_atstring<date-time>engagementobject | nullAggregated email engagement rollup for this contact. All fields are nil-safe: when no rollup row exists yet, rating is "never", counts are 0, rates and timestamps are null.
channelsArray<ContactChannel>ContactChannel
objectidintegercontact_idintegerkindstringemailphonevaluestringsubscribedbooleanverifiedbooleanopt_in_atstring<date-time> | nullopt_out_atstring<date-time> | nullsent_countintegerfail_countintegerdataobjectcreated_atstring<date-time>updated_atstring<date-time>ImageAsset
objectmedia_kindstringimagemedia_urlstring<uri>image_urlstring<uri>signed_idstringfilenamestringcontent_typestringbyte_sizeintegerwidthinteger | nullIntrinsic pixel width when detectable.
heightinteger | nullIntrinsic pixel height when detectable.
ContactList
objectidintegeraccount_idintegerbrand_idinteger | nullnamestringcontacts_countintegersegment_idinteger | nullstalebooleanlast_populated_atstring<date-time> | nullcreated_atstring<date-time>updated_atstring<date-time>BulkListContactsRequest
objectactionstringaddremoverequiredAdd existing contacts to the list or remove them from it.
emailsArray<string>requiredBulkListContactsResponse
objectactionstringaddremovelist_idintegeraddedintegerContacts newly added for add actions
removedintegerContacts removed for remove actions
already_in_listArray<string>not_in_listArray<string>not_foundArray<string>invalid_emailsArray<string>DirectUploadCreateRequest
objectpurposestringimportimagemedia_assetSet to import for CSV contact imports, or image/media_asset for image media assets.
blobobjectrequiredDirectUpload
objectsigned_idstringSubmit this value to endpoints that consume direct uploads.
filenamestringbyte_sizeintegercontent_typestring | nulldirect_uploadobjectImportPolicy
objectImport limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.
standingstringrequiredThe account standing the limits derive from.
trustedmax_rowsinteger | nullrequiredRow ceiling for one import. Null means no row ceiling for this standing.
nullmax_file_size_bytesintegerrequired2147483648max_file_size_mbintegerrequired2048max_active_importsintegerrequired10create_rate_limit_per_minuteintegerrequired10direct_upload_rate_limit_per_minuteintegerrequired30write_modesArray<string>realshadowdry_runrequiredImportSpec
objectresourcestringcontactsleadsrequiredparserstringdefaultrequireduiobjectrequired_rulesobjectfieldsArray<object>requiredDefault contacts consent targets use polarity-explicit labels.
email_status aliases: Email marketing, Subscribed, Subscription status,
opt_in, opt in, opt-in, subscribed_email, email_status.
email_opt_out aliases: Unsubscribed, Opted out, opt_out, opt out, email_opt_out.
opt_in_at aliases: Opt In Date, consent date, opt_in_at.
Header matching ignores case, surrounding whitespace and a leading BOM.
Bare Status requires explicit mapping; it is never a consent alias.
A date-valued Opt-in column must be remapped to Opt In Date or Skip.
Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.
ImportGuardrail
objectHow this import stands against the account's standing row limit.
tierstringautocontact_usrequiredauto when the row count is within the standing limit; contact_us when it is above it and the import halted.
statusstringokcontact_salesrequiredClient-facing guardrail status vocabulary.
standingstringrequiredThe account standing the limit derives from.
probationmax_rowsinteger | nullrequiredRow ceiling for the standing. Null means no row ceiling.
250000Import
objectidintegerresourcestringcontactsleadsparserstringdefaultstatusstringpendingprocessingfailedcanceledcompletecontact_ustotal_rowsinteger | nullsuccess_rowsinteger | nullfailed_rowsinteger | nullemail_rowsobject | nullEmail row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.
warning_rowsintegerRows with ingest-time warnings (at most one per row), including skipped optional channels/email consent, ignored historical dates or conflicting declarations resolved to unsubscribe. These diagnostics may remain if a later bulk flush fails; success_rows credits committed writes only.
progressobjectCanonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.
import_errorsArray<Array<integer | string>>Row-level errors as [line_number, message, source]. invalid_consent rejects unusable status before buffering when an email is usable; other valid rows continue. A failed bulk flush is a batch failure, not a row error for every buffered row.
import_warningsArray<Array<integer | string>>Bounded samples as [line_number, message, reason]. All warning messages for a row are combined; the first channel/parser reason remains primary. Consent reasons include conflicting_consent, invalid_opt_in_date and email_consent_skipped. Existing single-cause reasons are unchanged.
columnsobject | nulloptionsobject | nullassigned_list_idsArray<integer>assigned_listsArray<object>guardrailImportGuardrailHow this import stands against the account's standing row limit.
flows_not_startedobject | nullLive flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.
started_atstring<date-time> | nullended_atstring<date-time> | nullcreated_atstring<date-time>Export
objectidintegerresourcestringcontactsleadsformatstringcsvstatusstringpendingprocessingcompletefailedtotal_rowsinteger | nullrows_writtenintegerRows written so far; the live numerator against total_rows.
error_messagestring | nullreadybooleanTrue once the export is complete and the file is available.
download_pathstring | nullPath to download the CSV; present only when ready is true.
progressobjectLive job-progress block, updated as the export streams. status
normalizes the job lifecycle, pct is the completion percentage
(null while the row count is still unknown), and stages is the
ordered Queued to Building to Ready funnel.
started_atstring<date-time> | nullended_atstring<date-time> | nullcreated_atstring<date-time>SavedView
objectidintegersurfacestringcontactssendingactivitynamestringvisibilitystringprivatesharedfiltersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
layoutSavedViewLayout | nullTable layout preset for contacts surface views. Only present when surface = contacts.
ownerbooleanTrue when the current user is the creator of this view
created_atstring<date-time>updated_atstring<date-time>SavedViewLayout
objectTable layout preset for contacts surface views. Only present when surface = contacts.
columnsArray<string>Ordered list of column keys to display
sortobjectSegment
objectidintegeraccount_idintegerbrand_idinteger | nullnamestringoriginstringusersystemWho owns this segment. user (default) — created and managed by the user;
system — curated by the platform (Champions, Loyal, At-Risk, Dormant, New,
Suppressed, Recently unsubscribed, Bounced).
System segments cannot be renamed or deleted via the API.
filtersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
cached_countinteger | nullLast asynchronously refreshed contact count for this segment.
count_computed_atstring<date-time> | nullWhen cached_count was last refreshed.
created_atstring<date-time>updated_atstring<date-time>SegmentFilterExpression
objectRequest-side audience filter grammar. Use a flat array for ordinary
AND filters, { "operator": "and", "children": [...] } for the legacy
expression wrapper, or { "op": "and"|"or"|"not", "conditions": [...] }
for nested boolean logic. NOT groups must contain exactly one condition.
Segment filters are validated fail-closed. Unknown filter names,
globally invalid predicates, type-incompatible predicates, bad date
values, invalid enum values, and unsupported rolling-window filters
return a 422 invalid_filter error instead of silently widening an
audience.
operatorstringandrequirednotbooleanfalsefalseLegacy flat-AND wrapper does not carry NOT; use BooleanSegmentFilterGroup for NOT.
Segment filters are validated fail-closed. Unknown filter names,
globally invalid predicates, type-incompatible predicates, bad date
values, invalid enum values, and unsupported rolling-window filters
return a 422 invalid_filter error instead of silently widening an
audience.
opstringandornotrequiredNested filter nodes. NOT groups must contain exactly one condition.
FlatAndSegmentFilterExpression
objectoperatorstringandrequirednotbooleanfalsefalseLegacy flat-AND wrapper does not carry NOT; use BooleanSegmentFilterGroup for NOT.
Segment filters are validated fail-closed. Unknown filter names,
globally invalid predicates, type-incompatible predicates, bad date
values, invalid enum values, and unsupported rolling-window filters
return a 422 invalid_filter error instead of silently widening an
audience.
SegmentFilterNode
objectnamestringrequiredFilter name from nitro://schema: contact_first_name, contact_last_name,
contact_phone_number, contact_email, contact_country,
contact_subscribed_phone, contact_subscribed_email,
contact_created_at, contact_last_interacted_at,
contact_source, contact_tag,
contact_engagement_rating, contact_emails_sent, contact_last_opened_at,
contact_last_clicked_at, contact_unique_opens, contact_clicks,
contact_open_rate, contact_click_rate, contact_suppressed,
contact_suppression_reason, contact_bounced, contact_complained,
contact_soft_bounce_count, contact_unsubscribed_at, contact_list.
Catalogued custom and
enrichment fields are exposed as contact_data_
predicatestringrequiredRansack predicate: eq, not_eq, cont, not_cont, start, end,
gt, lt, gteq, lteq, present, blank, true, false, in, not_in,
within_days, not_within_days. Read /v1/my/flows/spec or
nitro://schema for the predicates allowed by each filter type.
valueanyrequiredFilter value — string, number, boolean, array of strings for in/not_in predicates (e.g. ["engaged","warm"] for contact_engagement_rating in), or array of list ids for contact_list.
typestringeventrequiredeventstringrequiredCustom or known event name, e.g. first_send, project_created, checkout.
predicatestringperformednot_performedcount_at_leastcount_at_mostrequiredvalueinteger>= 1Required for count_at_least and count_at_most.
within_daysinteger>= 1Optional rolling event recency window.
sincestring<date-time>Optional absolute event recency cutoff.
predicatestringperformednot_performedrequiredpredicatestringcount_at_leastcount_at_mostrequiredopstringandornotrequiredconditionsArray<any>requiredNested filter nodes. NOT groups must contain exactly one condition.
BooleanSegmentFilterGroup
objectopstringandornotrequiredNested filter nodes. NOT groups must contain exactly one condition.
SegmentFilters
arraySegment filters are validated fail-closed. Unknown filter names,
globally invalid predicates, type-incompatible predicates, bad date
values, invalid enum values, and unsupported rolling-window filters
return a 422 invalid_filter error instead of silently widening an
audience.
SegmentPreview
objectcountintegerLive count of contacts matching the supplied filters.
sampleArray<object>Bounded contact sample for quick verification.
overlapArray<object>Bounded overlap with existing segments.
AttributeSegmentFilter
objectnamestringrequiredFilter name from nitro://schema: contact_first_name, contact_last_name,
contact_phone_number, contact_email, contact_country,
contact_subscribed_phone, contact_subscribed_email,
contact_created_at, contact_last_interacted_at,
contact_source, contact_tag,
contact_engagement_rating, contact_emails_sent, contact_last_opened_at,
contact_last_clicked_at, contact_unique_opens, contact_clicks,
contact_open_rate, contact_click_rate, contact_suppressed,
contact_suppression_reason, contact_bounced, contact_complained,
contact_soft_bounce_count, contact_unsubscribed_at, contact_list.
Catalogued custom and
enrichment fields are exposed as contact_data_
predicatestringrequiredRansack predicate: eq, not_eq, cont, not_cont, start, end,
gt, lt, gteq, lteq, present, blank, true, false, in, not_in,
within_days, not_within_days. Read /v1/my/flows/spec or
nitro://schema for the predicates allowed by each filter type.
valueanyrequiredFilter value — string, number, boolean, array of strings for in/not_in predicates (e.g. ["engaged","warm"] for contact_engagement_rating in), or array of list ids for contact_list.
EventSegmentFilter
objecttypestringeventrequiredeventstringrequiredCustom or known event name, e.g. first_send, project_created, checkout.
predicatestringperformednot_performedcount_at_leastcount_at_mostrequiredvalueinteger>= 1Required for count_at_least and count_at_most.
within_daysinteger>= 1Optional rolling event recency window.
sincestring<date-time>Optional absolute event recency cutoff.
predicatestringperformednot_performedrequiredpredicatestringcount_at_leastcount_at_mostrequiredCampaign
objectidintegeraccount_idintegerbrand_idinteger | nullstatusstringdraftactivepausedcompletedapproval_statestringdraft_revision_idinteger | nulldraft_revision_digeststring | nulldraft_approval_statestring | nullpending_reviewapprovedrejectedactive_revision_idinteger | nullactive_revision_digeststring | nullhas_unpublished_changesbooleanchannelstringemailsmsnamestringdataobjectscheduled_atstring<date-time> | nullsent_countintegerdashboard_urlstring<uri> | nullCanonical dashboard URL with the /my route prefix.
preview_urlstring<uri> | nullSigned, expiring public preview URL for the current template version.
recipient_snapshotobject | nullLast send snapshot. Values are captured at send time and are not a live audience estimate.
last_send_recipientsinteger | nullAlias for the last dispatched recipient snapshot stored in data.recipients.
deliveryCampaignDeliverySummary | nullPresent while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.
engagementEngagementBucket & objectrevenueRevenueReportAttributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.
editablebooleanread onlyTrue when the campaign's content/audience/template can be edited.
False for live, paused, completed, cancelled, archived, and for
scheduled campaigns within 5 minutes of their scheduled_at. When
false, PUT update accepts only name-only payloads and status
transitions (Resume / Cancel); anything else returns 422
campaign_locked. Use POST /duplicate to fork into a new draft.
created_atstring<date-time>updated_atstring<date-time>triggerFlowTriggertemplateTemplate | nulltemplatesArray<Template>experimentCampaignExperimentThe test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.
CampaignDeliverySummary
objectcapacity_recoveryDeliveryCapacityRecoveryInformational recovery at 80 percent used, exhaustion, or when a campaign exceeds remaining allowance. Never denies a send or promises that payment or verification bypasses safety. Actions come from the shared backend projection; only offer verification when new valid proof can improve standing. Capacity counters and usage_percent are present for the account's commercial allowance only; shared probation notices never disclose platform totals.
campaign_send_tokenstring | nullrequiredstatusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequiredrecipientsintegerrequiredRecipient count captured for the active send.
sentintegerrequiredfailedintegerrequiredpendingintegerrequiredCampaignDeliveryProgress
objectexperimentCampaignExperimentThe test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.
capacity_recoveryDeliveryCapacityRecoveryInformational recovery at 80 percent used, exhaustion, or when a campaign exceeds remaining allowance. Never denies a send or promises that payment or verification bypasses safety. Actions come from the shared backend projection; only offer verification when new valid proof can improve standing. Capacity counters and usage_percent are present for the account's commercial allowance only; shared probation notices never disclose platform totals.
stop_reasonstring | nullWhy a stopped send stopped, such as email_under_review for one held by the safety check.
safety_reviewobject | nullFor a send the safety check held, blocked or couldn't read: what the account may be told (the reason and fix as a person reads them), the fix to paste to an agent, and what it is offered.
campaign_send_tokenstring | nullrequiredstatusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequiredrecipientsintegerrequiredRecipient count captured for the active send.
sentintegerrequiredfailedintegerrequiredpendingintegerrequiredterminalbooleanrequiredTrue when clients can stop polling.
poll_after_secondsinteger | nullrequiredSuggested polling delay for active sends.
MailActionDescription
objectA Mail Action Protocol 0.3 description. The canonical MailSchema core schema is authoritative; this schema restates its shape.
@contextstringhttps://mailschema.org/contexts/map-0.3.jsonldrequired@typestringMailActionrequired@idstring<uri>requiredIdentifies the interaction.
profilestringhttps://mailschema.org/profiles/map/0.3requiredtypeobjectrequiredissuedAtstring<date-time>requiredexpiresAtstring<date-time>requiredinLanguagestringrequiredserviceobjectrequiredrecipientstring<email>requiredsubjectobjectrequiredtermsobjectrequireddetailsobjectrequiredDefined by the type contract's details schema.
operationsArray<object>requiredhumanobjectrequiredSendApproval
objectidintegerrequiredcampaign_idintegerrequiredcan_decidebooleanrequiredWhether the signed-in person may decide it, as the account owner or a direct account admin.
statestringpendingapproveddeclinedexpiredwithdrawnrequiredwithdrawn means the send stopped before anyone decided. After approval, delivery_status tells a send in progress from a finished one.
decided_atstring<date-time>delivery_statusstringpendingin_progresscompletedfailedcancelledrequiredcontentobjectrequiredbccstringThe address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.
The Campaign Send Approval 0.1 description of this send's exact terms.
MessageSendResult
objectidintegerchannelstringemailsmstostringrecipientsobjectFull normalized email envelope, visible only to authorized account readers. Returned for email messages.
subjectstring | nullstatusstringqueuedsentfailedprovider_idstring | nullrfc_message_idstring | nullActual email Message-ID recorded after provider acceptance; null until available. Use it for In-Reply-To and References, without deriving it from provider_id.
flow_idinteger | nullSource flow ID (null for transactional)
source_typestring | nullcampaignflowtestcampaign, flow, test, or null (transactional)
source_namestring | nullName of source campaign or flow
status_reason_codestring | nullStable reason for a queued or failed dispatch, or the provider feedback on a sent email test.
status_reasonstring | nullHuman-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.
status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdeliveryBroad category for status_reason.
failure_codestring | nullStable machine-readable failure reason; present only when status is failed.
failure_reasonstring | nullHuman-readable failure explanation; present only when status is failed.
failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdeliveryBroad category for failure_reason; present only when status is failed.
sent_atstring<date-time> | nullcreated_atstring<date-time>ignored_fieldsArray<string>requiredTop-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.
TestSendResult
objectoutcomestringsentpartialpendingheldfaileddry_rundeliveredDispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.
sentintegerrequiredNumber of tests accepted by the sending provider.
pendingintegerheldintegerTests awaiting content review; not sent and not automatically replayed after approval.
failedintegerdry_runbooleanresultsArray<object>requiredMessage
objectidintegerchannelstringemailsmstostringrecipientsobjectFull normalized email envelope, visible only to authorized account readers. Returned for email messages.
subjectstring | nullstatusstringqueuedsentfailedprovider_idstring | nullrfc_message_idstring | nullActual email Message-ID recorded after provider acceptance; null until available. Use it for In-Reply-To and References, without deriving it from provider_id.
flow_idinteger | nullSource flow ID (null for transactional)
source_typestring | nullcampaignflowtestcampaign, flow, test, or null (transactional)
source_namestring | nullName of source campaign or flow
status_reason_codestring | nullStable reason for a queued or failed dispatch, or the provider feedback on a sent email test.
status_reasonstring | nullHuman-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.
status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdeliveryBroad category for status_reason.
failure_codestring | nullStable machine-readable failure reason; present only when status is failed.
failure_reasonstring | nullHuman-readable failure explanation; present only when status is failed.
failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdeliveryBroad category for failure_reason; present only when status is failed.
sent_atstring<date-time> | nullcreated_atstring<date-time>Suppression
objectAccount suppression row with bounded source-event diagnostics.
idintegeremailstring<email>reasonstringhard_bouncesoft_bouncecomplaintmanualadminunsubscribeverificationmarketing_withheldunconfirmedscopestringaccount_scopedbrand_scopedbrand_idinteger | nullBrand affected by a brand-specific stop.
activebooleancontact_idinteger | nullsource_providerstring | nullsource_event_idstring | nullprovider_diagnosticstring | nullBounded diagnostic text extracted from the provider feedback event, when retained.
bounce_typestring | nullhardsoftbounce_subtypestring | nullcomplaint_feedback_typestring | nullevent_occurred_atstring<date-time> | nullexpires_atstring<date-time> | nullcreated_atstring<date-time>updated_atstring<date-time>WebhookEventType
stringWebhook
objectidintegerurlstring<uri>eventsArray<WebhookEventType>email.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledenabledbooleanstatusstringactivefailingdisabledfailing while deliveries fail; an endpoint failing for 3 days is turned off.
failing_sincestring<date-time> | nullsecretstringStandard Webhooks signing secret (whsec_...). Masked unless revealed.
last_deliveryobject | nullcreated_atstring<date-time>updated_atstring<date-time>WebhookWriteRequest
objecturlstring<uri>HTTPS URL that resolves only to public addresses, without credentials.
eventsArray<WebhookEventType>email.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledenabledbooleanWebhookDelivery
objectidintegerevent_idstring<uuid>Sent as webhook-id (evt_<event_id>), stable across retries.
event_typeWebhookEventTypeemail.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledstatusstringpendingdeliveredfailedattemptsintegerlast_response_statusinteger | nulllast_errorstring | nullnext_attempt_atstring<date-time>payloadWebhookEventPayloadcreated_atstring<date-time>updated_atstring<date-time>WebhookEventPayload
objecttypeWebhookEventTypeemail.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabledrequiredtimestampstring<date-time>requireddataobjectrequiredWebhookReceivedEventPayload
objecttypestringemail.receivedrequiredtimestampstring<date-time>requiredWhen the message arrived.
dataobjectrequiredCampaignCompletedWebhookData
objectcampaign_idintegerrequiredcampaign_namestring | nullrequiredcampaign_send_idinteger | nullrequiredrecipientsinteger | nullrequiredRecipients the send planned.
completed_atstring<date-time> | nullrequiredCampaignFailedWebhookData
objectcampaign_idintegerrequiredcampaign_namestring | nullrequiredcampaign_send_idinteger | nullrequiredrequested_recipientsinteger | nullrequiredsent_countinteger | nullrequiredfailure_reasonstringrequiredA public reason code, e.g. campaign_delivery_failed.
next_actionstringrequiredWhat to do before sending again.
CampaignStoppedWebhookData
objectcampaign_idintegerrequiredcampaign_namestring | nullrequiredmetricstring | nullrequiredBounce rate or Complaint rate.
ratenumber | nullrequiredThe measured rate in percent.
thresholdnumber | nullrequiredThe stop threshold in percent.
total_sendsinteger | nullrequiredhard_bouncesinteger | nullrequiredcomplaintsinteger | nullrequirednext_actionstring | nullrequiredFlowPausedWebhookData
objectflow_idintegerrequiredflow_namestring | nullrequiredmetricstring | nullrequiredBounce rate or Complaint rate.
ratenumber | nullrequiredThe measured rate in percent.
thresholdnumber | nullrequiredThe pause threshold in percent.
SendingPausedWebhookData
objectreasonstring | nullrequiredWhy, e.g. critical_bounce_rate. Null when the pause is not explained.
sending_pausedbooleanrequiredoccurred_atstring<date-time> | nullrequiredSendingLimitWebhookData
objectstatestringapproachingreachedrequiredlabelstringrequireddetailstringrequiredusage_percentintegerrequiredShare of the allowance used.
capacityobjectrequiredretry_atstring<date-time> | nullrequiredWhen capacity frees up
upgrade_urlstring | nullrequiredWhere an owner on the free plan can upgrade.
ImportCompletedWebhookData
objectresourcestring | nullcontactsleadsnullrequiredimport_idintegerrequiredlist_namestring | nullrequiredsuccess_rowsinteger | nullrequiredfailed_rowsinteger | nullrequiredtotal_rowsinteger | nullrequiredImportFailedWebhookData
objectimport_idinteger | nullrequiredreasonstring | nullrequiredfailed_rowsinteger | nullrequiredDomainVerificationLostWebhookData
objectdomain_idintegerrequireddomainstringrequiredfailingArray<string>requiredThe DNS record families that failed, e.g. dkim.
DomainDnsDegradedWebhookData
objectdomain_idinteger | nullrequireddomainstringrequiredfailingArray<string>requiredThe DNS record families that failed, e.g. dkim.
classificationstring | nullrequiredactionstring | nullrequiredWebhookDisabledWebhookData
objectwebhook_idintegerrequiredurlstringrequiredThe endpoint URL without credentials or query.
failing_sincestring<date-time> | nullrequiredChatMessage
objectidintegerrolestringuserassistanttoolsystemcontentstringCredential-shaped values are redacted before display.
tool_callsArray<object>actionsArray<object>attachmentsArray<object>Images the person added to the message, from the brand's image library.
sequenceintegercreated_atstring<date-time>ChatSession
objectidintegeraccount_idintegerbrand_idintegertitlestringstatusstringactiveclosedfailedstarted_atstring<date-time>last_message_atstring<date-time>message_countintegercreated_atstring<date-time>updated_atstring<date-time>ChatSessionDetail
objectidintegeraccount_idintegerbrand_idintegertitlestringstatusstringactiveclosedfailedstarted_atstring<date-time>last_message_atstring<date-time>message_countintegercreated_atstring<date-time>updated_atstring<date-time>messagesArray<ChatMessage>EmailContentFormat
stringDurable email presentation. New templates default to designed; omitted edits preserve the stored value. A supplied value must equal the stored format for edits or the authorized selected source format for copies; newly authored Flow content can select designed or plain. AI composition retains its own authorized source-format contract. Null, invalid and mismatched edits fail validation. Plain uses body as author text and produces minimal HTML plus a real text alternative, with required compliance and current Brand tracking policy. It is not no-HTML MIME. Only email templates support plain. This differs from message format, which describes its template/raw/plain source shape.
Template
objectidintegernamestring | nullflow_idinteger | nullaction_idinteger | nullversionintegersubjectstring | nullbodystring | nullcontent_formatEmailContentFormatdesignedplainDurable email presentation. New templates default to designed; omitted edits preserve the stored value. A supplied value must equal the stored format for edits or the authorized selected source format for copies; newly authored Flow content can select designed or plain. AI composition retains its own authorized source-format contract. Null, invalid and mismatched edits fail validation. Plain uses body as author text and produces minimal HTML plus a real text alternative, with required compliance and current Brand tracking policy. It is not no-HTML MIME. Only email templates support plain. This differs from message format, which describes its template/raw/plain source shape.
plain_text_modestringderivedcustomblock_usageobjectLibrary templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.
preheaderstring | nullfrom_namestring | nullfrom_emailstring | nullreply_tostring | nulldesignEmailDesign | nullvariablesobjectgeneration_provenanceGenerationProvenanceCandidate-bound generation evidence. Save endpoints accept only
state: candidate values returned by the generation endpoint. Resource
responses may return state: accepted as read-only history.
created_atstring<date-time>updated_atstring<date-time>GenerationProvenance
objectCandidate-bound generation evidence. Save endpoints accept only
state: candidate values returned by the generation endpoint. Resource
responses may return state: accepted as read-only history.
statestringcandidateacceptedrequiredevent_idintegerrequiredcandidate_locatorstringgenerated_slice_digeststringacceptance_idintegersaved_authored_digeststringedit_relationstringidenticaleditedEmailLibraryTemplate
objectidstringnamestringcategorystringtagsArray<string>descriptionstringsubjectstringSuggested subject line
preheaderstringSuggested preheader
designEmailDesignEmail template design document
preview_htmlstring | nullbranded_designEmailDesignSame layout with palette overrides stripped so brand colors apply
branded_preview_htmlstring | nullPublicEmailCatalogTemplate
objectidstringrequiredrevisionstringDigest of the concrete public design.
collectionstringbrand_studiesPresent for a brand concept study; originals retain their existing response shape.
studyobjectnamestringrequiredcategorystringrequiredtagsArray<string>requireddescriptionstringrequiredsubjectstringrequiredpreheaderstringrequiredEmail template design document
GuestFlowDemo
objectOne anonymous flow demo. The scanned brand is accepted automatically and shown while the flow is generated. A demo with no state on the server reads as expired.
statusstringscanninggeneratingreadyfailedexpiredrequiredrevisionintegerAdvances with each brand edit or generation retry. Absent when expired.
domainstringgoalstringbrandobjectScanned Brand Kit fields, present once the scan has completed.
logo_urlstringScanned logo
flowobjectThe generated draft for the current revision, present when ready.
failed_stagestringscangeneratePresent when failed. A failed scan cannot be retried; start again.
messagestringVisitor copy, present when failed or expired.
error_codestringflow_demo_attempts_exhaustedPresent when a generation failed on the demo's last attempt: it cannot be retried, and message offers an account instead.
TemplateSummary
objectidintegernamestring | nullversionintegercontent_formatEmailContentFormatdesignedplainDurable email presentation. New templates default to designed; omitted edits preserve the stored value. A supplied value must equal the stored format for edits or the authorized selected source format for copies; newly authored Flow content can select designed or plain. AI composition retains its own authorized source-format contract. Null, invalid and mismatched edits fail validation. Plain uses body as author text and produces minimal HTML plus a real text alternative, with required compliance and current Brand tracking policy. It is not no-HTML MIME. Only email templates support plain. This differs from message format, which describes its template/raw/plain source shape.
preview_htmlstring | nullRendered preview, present only with ?include_previews=1
subjectstring | nullpreheaderstring | nullflow_idinteger | nullsection_countintegersection_typesArray<string>created_atstring<date-time>updated_atstring<date-time>Flow
objectidintegeraccount_idintegerbrand_idinteger | nullstatusstringdraftlivepausedarchivedcancelledapproval_statestringnamestringgoalstring | nulltriggerFlowTriggerOutputTrigger as returned by Flow::Format.dump
reply_readinessobject | nullLocal receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
sent_countintegerengagementEngagementBucket & objectrevenueRevenueReportAttributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.
draft_revision_idinteger | nulldraft_revision_digeststring | nulldraft_approval_statestring | nullpending_reviewapprovedrejectedactive_revision_idinteger | nullactive_revision_digeststring | nullhas_unpublished_changesbooleanunpublished_changeobject | nullNull when what was last saved is what runs. Otherwise a live or
paused flow's latest saved revision is not live yet. On a read of
one flow and on a save response, blockers says why: each check
that refuses to publish it, and on a save response the refusal
that save received (including Safe Mode for an API key, and
plan_required in Setup mode, listed whatever else refuses). When
no check explains it, a note that the change isn't live leads,
followed by Safe Mode if it's on. The flow list leaves blockers
out, as does a read of one flow with include_blockers=false; read
the flow for them.
saves_publishbooleanTrue when a save with publish: true publishes the change (a live
or paused flow). False when a save stays a draft, as for a draft or
archived flow.
created_atstring<date-time>updated_atstring<date-time>templatesArray<Template>FlowResumePlan
objectflow_idintegerrequiredstatusstringdraftlivepausedarchivedcancelledrequiredopen_journey_countinteger>= 0requiredcontact_countinteger>= 0requiredwaiting_journey_countinteger>= 0requiredscheduled_journey_countinteger>= 0requiredhas_unpublished_changesbooleanrequireddraft_approval_statestring | nullpending_reviewapprovedrejectedrequires_choicebooleanrequiredallowed_modesArray<string>new_contacts_onlycontinue_existingrequiredrecommended_modestringnew_contacts_onlyrequiredFlowTemplate
objectLean flow template card for index listings.
idstringTemplate slug (e.g. welcome)
type_labelstringdescriptionstringcategorystringiconstringFont Awesome icon name for the template's card, without the fa- prefix.
needs_listbooleanWhether creating it takes trigger.contact_list_id, the brand list it starts on.
brand_writablebooleanWhether POST /v1/my/flows/generate can write this template for the brand.
email_countintegerstep_countintegerFlowTemplateDetail
objectLean flow template card for index listings.
idstringTemplate slug (e.g. welcome)
type_labelstringdescriptionstringcategorystringiconstringFont Awesome icon name for the template's card, without the fa- prefix.
needs_listbooleanWhether creating it takes trigger.contact_list_id, the brand list it starts on.
brand_writablebooleanWhether POST /v1/my/flows/generate can write this template for the brand.
email_countintegerstep_countintegerFull flow template including the graph, ready for POST /v1/my/flows.
triggerobjectTrigger definition (pass as-is to POST /v1/my/flows trigger param)
stepsArray<object>Step definitions (pass as-is to POST /v1/my/flows steps param). Each email
step carries its key, which becomes its action name, and, for a template
an agent can select, its job and objective.
EngagementBucket
objectEngagement for a cohort of emails: every email of the resource (or, nested as
account, every email of the brand), counting all their engagement whenever it
arrived. An email is one message the provider accepted; test sends are excluded.
Each email counts at most once toward opens however many times it was opened
and however many observers (tracking pixel, provider webhook) reported it.
sentintegerrequiredEmails the provider accepted in this bucket (test sends excluded).
deliveredintegerrequiredProvider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.
non_bouncedintegerAccepted emails minus known bounces; the denominator of open and click rates.
unconfirmedintegerAccepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.
opensintegerrequiredNon-bounced emails with at least one observed open. Known scanners are excluded; privacy tools can register opens automatically. This is not proof of a human read.
total_opensintegerrequiredAll counted open observations of non-bounced emails, including repeat opens, so
total_opens >= opens. A volume figure, never a rate numerator.
open_ratenumber<float> | nullrequiredopens / non_bounced, a fraction between 0 and 1 rounded to 4 decimal places.
Null without a denominator, and for the account bucket when fewer than
Report::Engagement::ACCOUNT_BASELINE_MIN_SENT emails were sent.
Engagement
objectEngagement for a cohort of emails: every email of the resource (or, nested as
account, every email of the brand), counting all their engagement whenever it
arrived. An email is one message the provider accepted; test sends are excluded.
Each email counts at most once toward opens however many times it was opened
and however many observers (tracking pixel, provider webhook) reported it.
Engagement for a cohort of emails: every email of the resource (or, nested as
account, every email of the brand), counting all their engagement whenever it
arrived. An email is one message the provider accepted; test sends are excluded.
Each email counts at most once toward opens however many times it was opened
and however many observers (tracking pixel, provider webhook) reported it.
sentintegerrequiredEmails the provider accepted in this bucket (test sends excluded).
deliveredintegerrequiredProvider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.
non_bouncedintegerAccepted emails minus known bounces; the denominator of open and click rates.
unconfirmedintegerAccepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.
opensintegerrequiredNon-bounced emails with at least one observed open. Known scanners are excluded; privacy tools can register opens automatically. This is not proof of a human read.
total_opensintegerrequiredAll counted open observations of non-bounced emails, including repeat opens, so
total_opens >= opens. A volume figure, never a rate numerator.
open_ratenumber<float> | nullrequiredopens / non_bounced, a fraction between 0 and 1 rounded to 4 decimal places.
Null without a denominator, and for the account bucket when fewer than
Report::Engagement::ACCOUNT_BASELINE_MIN_SENT emails were sent.
EngagementCohortBucket
objectEngagement of a cohort of emails: the messages the provider accepted (test sends excluded), each counted once however many times or by however many observers (tracking pixel, provider webhook) it was opened or clicked. Rates are fractions between 0 and 1 rounded to 4 decimal places, null without a denominator.
sentintegerrequiredEmails the provider accepted.
deliveredintegerrequiredProvider-confirmed deliveries excluding final bounces.
non_bouncedintegersent - bounced; the open and click rate denominator.
unconfirmedintegersent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.
bouncedintegerrequiredEmails that bounced.
opensintegerrequiredNon-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.
total_opensintegerrequiredCounted open observations including repeats; never a rate numerator.
clicksintegerrequiredNon-bounced emails clicked at least once; clicks <= non_bounced.
total_clicksintegerrequiredCounted click observations of non-bounced emails.
forwardsintegerrequiredNon-bounced emails with a recorded forward.
delivered_ratenumber<float> | nullrequireddelivered / sent.
open_ratenumber<float> | nullrequiredopens / non_bounced.
click_ratenumber<float> | nullrequiredclicks / non_bounced.
bounce_ratenumber<float> | nullrequiredbounced / sent.
MessageSendsEngagement
objectintervalstringhourdaymonthrequiredSeries bucket size (hour for today, month for all time, otherwise day).
Engagement of a cohort of emails: the messages the provider accepted (test sends excluded), each counted once however many times or by however many observers (tracking pixel, provider webhook) it was opened or clicked. Rates are fractions between 0 and 1 rounded to 4 decimal places, null without a denominator.
seriesArray<object & EngagementCohortBucket>requiredOne entry per interval of the window (zero-filled), plus any later interval with sends; entries add up to summary.
has_sendsbooleanrequiredWhether the source has ever accepted a non-test email (outside the window too).
MessageSendsRow
objectsource_typestringcampaignflowtransactionaltestrequiredrow_keystringrequiredsource_idinteger | nullCampaign or flow id; null for transactional and test rows.
source_namestringrequireddatestring<date> | nullCreation day of a transactional or test row.
subjectstring | nullrecipientsstring | nullrecipients_countintegertotalintegerrequiredMessages in the row (every status and channel) within the window.
sentintegerrequiredMessages of the row the provider accepted (every channel).
failedintegerrequiredqueuedintegerrequiredlatest_failure_codestring | nulllatest_failure_reasonstring | nulllatest_failure_categorystring | nulllast_sent_atstring<date-time> | nulldeliveredintegerrequiredThe row's provider-confirmed deliveries (0 on test and failed-only rows).
non_bouncedintegerAccepted non-test emails minus known bounces.
unconfirmedintegerAccepted non-test emails without a final provider outcome.
openedintegerrequiredNon-bounced emails of the row opened at least once; privacy image loads can count.
clickedintegerrequiredNon-bounced emails of the row clicked at least once.
open_ratenumberrequiredPercentage (0-100, 1 dp) of non_bounced; 0 without a denominator.
click_ratenumberrequiredPercentage (0-100, 1 dp) of non_bounced; 0 without a denominator.
deliveryobjectSend progress of a campaign row with an active send (same projection as the campaign delivery endpoints).
MessageSendsCounts
objectMessage counts for the filter pills, over the same window as the rows.
allintegerrequiredMessages of every source in the since window (with failed).
campaignintegerrequiredflowintegerrequiredtransactionalintegerrequiredtestintegerrequiredtimeobjectrequiredMessages of the selected source (with failed) per window.
RevenueMessageBreakdown
objectmessage_idintegersubjectstring | nullsent_atstring<date-time> | nullcurrencystring | nullDominant attributed order currency for this message row.
mixed_currencybooleanTrue when attributed orders included more than one currency before dominant-currency filtering.
deliveredintegerattributed_ordersintegerattributed_revenue_centsintegerNet attributed revenue in cents from the orders ledger.
revenue_per_recipientnumber<float> | nullconversion_ratenumber<float> | nullattributed_aovnumber<float> | nullRevenueReport
objectAttributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.
attribution_labelstringAttributed revenue. Last click, 7-day window.currencystring | nullDominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.
mixed_currencybooleanTrue when attributed orders included more than one currency before dominant-currency filtering.
attributed_revenue_centsintegerNet attributed revenue in cents from the orders ledger.
deliveredintegerattributed_ordersintegerrevenue_per_recipientnumber<float> | nullNet attributed revenue in major currency units divided by delivered recipients.
conversion_ratenumber<float> | nullAttributed paid orders divided by delivered recipients.
attributed_aovnumber<float> | nullNet attributed revenue in major currency units divided by attributed paid orders.
message_breakdownArray<RevenueMessageBreakdown>ProfileEnrichmentAudience
objectExactly one same-Brand selection. Existing identity and profile ownership are preserved.
contact_idsArray<integer>FlowTrigger
objectidintegerflow_idintegereventstringaudience_typestring | nulllistssegmentall_contactsExplicit campaign audience target; null means no audience selected.
segment_idinteger | nullcontact_list_idinteger | nulldeprecatedDeprecated — use contact_list_ids
contact_list_idsArray<integer>Contact list IDs targeted by this trigger
exclude_segment_idsArray<integer>Segment IDs whose matching contacts are excluded from the recipient set
exclude_contact_list_idsArray<integer>Contact list IDs whose members are excluded from the recipient set
dataobject | nulltriggered_countintegerlast_triggered_atstring<date-time> | nullcreated_atstring<date-time>updated_atstring<date-time>FlowTriggerInput
objectstop_on_replybooleanfalseStop only the enrollment whose tracked email received a proven human reply. Requires monitored receiving.
reply_sourceobjectexit_eventsArray<string>New same-brand/contact events after journey entry stop future steps. Pinned in the approved revision; cannot recall a step already executing.
eventstringBuilt-in: contact_add, keyword, message, list_add, list_remove, product_view, checkout, cart_add, cart_remove, cart_abandoned, browse_abandoned. Custom: any lowercase alphanumeric with underscores.
audience_typestring | nulllistssegmentall_contactsExplicit campaign audience target; null means no audience selected.
segment_idinteger | nullcontact_list_idinteger | nulldeprecatedDeprecated — use contact_list_ids
contact_list_idsArray<integer>Contact list IDs to target
exclude_segment_idsArray<integer>Segment IDs whose matching contacts are excluded from the recipient set; pass [] to clear
dataobjectFlowTriggerOutput
objectTrigger as returned by Flow::Format.dump
stop_on_replybooleanreply_sourceobjectexit_eventsArray<string>eventstringsegment_idinteger | nullcontact_list_idinteger | nullexclude_segment_idsArray<integer>Segment IDs whose matching contacts are excluded from the recipient set
dataobject | nullFlowStepInput
objecttypestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscriberequiredcategoriesArray<ReplyCategory>branchesobjectEvery declared category key and other must have an explicit path. A branch node ends its sequence.
reply_allbooleanfalseccArray<string>bccArray<string>subjectstringEmail step: subject line
bodystringSMS body or email plain text
content_formatEmailContentFormatdesignedplainDurable email presentation. New templates default to designed; omitted edits preserve the stored value. A supplied value must equal the stored format for edits or the authorized selected source format for copies; newly authored Flow content can select designed or plain. AI composition retains its own authorized source-format contract. Null, invalid and mismatched edits fail validation. Plain uses body as author text and produces minimal HTML plus a real text alternative, with required compliance and current Brand tracking policy. It is not no-HTML MIME. Only email templates support plain. This differs from message format, which describes its template/raw/plain source shape.
plain_text_modestringderivedcustompreheaderstringEmail step: preheader
from_namestringfrom_emailstringreply_tostringdesignEmailDesignEmail template design document
durationinteger>= 0Wait step: seconds, positive unless send_at is configured
send_atstringFirst local occurrence at/after the original duration. Resume does not restart the delay. DST gaps use the first valid instant; folds use the first eligible occurrence.
time_zonestringIANA time zone for send_at. Defaults from the account owner or Etc/UTC and is pinned in the approved runtime.
filtersArray<AttributeSegmentFilter | any> | FlatAndSegmentFilterExpression | BooleanSegmentFilterGroupSplit step: condition filters
Split step: yes branch
Split step: no branch
event_namestringEmit event step: event to fire
forward_event_databooleanfalseevent_dataobjecttransactionalbooleanfalseFlowStepOutput
objectStep as returned by Flow::Format.dump
typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribecategoriesArray<ReplyCategory>branchesobjectreply_allbooleanccArray<string>bccArray<string>subjectstringbodystringcontent_formatEmailContentFormatdesignedplainPersisted presentation for an email step; defaults to designed.
preheaderstringdurationintegersend_atstringtime_zonestringfiltersArray<object>event_namestringforward_event_databooleanReplySource
objecttypestringanyrequiredtypestringflowcampaignmessagerequiredidinteger>= 1requiredExisting resource in the same brand.
ReplyCategory
objectkeystringrequiredStable branch key; other is reserved.
labelstringrequireddescriptionstringrequiredEvent
objectidintegeraccount_idintegercontact_idintegeruser_idintegereventstringamountnumber<double> | nulldataobjectidempotency_keystring | nullresource_uidstring | nullresource_namestring | nullresource_urlstring | nulltestbooleangeneratedbooleanchain_depthintegeripstring | nulluser_agentstring | nullbrowserstring | nullosstring | nulldevice_typestring | nullreferrerstring | nullutm_sourcestring | nullutm_mediumstring | nullutm_termstring | nullutm_contentstring | nullutm_campaignstring | nullcreated_atstring<date-time>updated_atstring<date-time>SubdomainSharingSummary
objectparentobjectrequireddestinationsArray<object>requireddestinations_truncatedbooleanrequiredpaginationobjectrequiredDomain
objectidintegerbrand_idinteger | nullnamestringproviderstringsesdefault_from_domainstringDomain Nitrosend will use for visible From addresses when this sending domain is selected.
subdomain_sharing_availablebooleanThe current principal can manage sharing on this verified apex.
sender_authorization_reasonstringmissing_sender_domainexact_inboxexact_mailboxshared_domain_requires_exact_inboxshared_domain_not_verifiedplatform_domainsender_domain_not_authorizedsending_domainunaligned_apex_supportedauthor_identity_not_verifiedauthor_domain_unalignedauthor_domainsender_domain_mismatchMachine-readable reason the default visible From domain is or is not authorized.
outstandingobject | nullWhat still stands between this domain and sending, as the next step, and when Nitrosend checks again automatically. Null once the domain and its From domain are verified and DNS is healthy. Verify reads DNS without delaying that check; one that finds the records newly in place makes it due at once.
integration_idinteger | nullstatusstringpendingverifieddmarc_policystringnonequarantinerejectEffective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
dmarc_recommended_policystringnonequarantinerejectNitrosend's recommended DMARC policy rung.
dmarc_observed_policystring | nullnonequarantinerejectLast live DMARC policy observed by Nitrosend.
dns_recordsDomainDnsRecords | nullinbound_setupDomainInboundSetup | nulldns_healthobject | nulldns_setup_statusstringuncheckedincompletereadyverifiedverified_atstring<date-time> | nullcreated_atstring<date-time>EntriSessionRequest
objectapex_mx_overridebooleanfalseExplicitly include the prepared company-inbox MX cutover in this session.
apex_mx_confirmationstringExact apex domain name being approved. Required when apex_mx_override is true.
EntriSessionValidationError
objectcapacity_recoveryDeliveryCapacityRecoveryInformational recovery at 80 percent used, exhaustion, or when a campaign exceeds remaining allowance. Never denies a send or promises that payment or verification bypasses safety. Actions come from the shared backend projection; only offer verification when new valid proof can improve standing. Capacity counters and usage_percent are present for the account's commercial allowance only; shared probation notices never disclose platform totals.
recovery_actionobjectContext-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.
codeintegerrequiredmessagestringrequirederrorbooleanrequirederror_codestring | nullOptional machine-readable error reason.
provisioning_idinteger | nullExisting provisioning row involved in a managed-account conflict.
retryablebooleanWhether retrying the same idempotent operation can succeed.
retry_atstring<date-time>Earliest recommended retry time for a retryable failure.
blockersArray<string>Machine-readable reasons the apex MX cutover cannot proceed.
DomainDnsRecords
objectsending_dns_recordsArray<DomainDnsRecord>receiving_dns_recordsArray<DomainDnsRecord>DomainDnsRecord
objectrecord_typestringnamestringrelative_namestringRecord name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.
valuestringprioritystring | nullvalidstring | nullpurposestring | nullrequiredboolean | nullmail_forwardingDomainMailForwarding | nullDomainMailForwarding
objectenabledbooleanrequiredroute_typestringlegacy_forward_allunmatched_forwardrequireddestination_typestringlegacy_mxsmtp_relayrequiredsetup_notestringrequiredDomainInboundSetup
objectmethodstringnoneprovider_forwardingmxrequiredstatusstringnot_configuredpendingactiveattentionrequiredrequires_inbox_selectionbooleanSeveral inboxes exist and no specific inbox was selected.
mx_scopestring | nullapexsubdomaininboxDomainInboundInbox | nullprovider_forwardingDomainProviderForwarding | nullapex_mxDomainApexMxSetup | nullDomainInboundInbox
objectidintegerrequiredaddressstring<email>requireddisplay_namestring | nullstatusstringactivedisabledarchivedrequiredDomainProviderForwarding
objectproviderstringgoogle_workspacemicrosoft_365zohootherrequiredforwarding_addressstring<email>requiredread onlyprobe_sent_atstring<date-time> | nullverified_atstring<date-time> | nullDomainApexMxSetup
objectmodestringstandaloneforward_allpreparationobjectpreparedbooleanrequiredconfiguredbooleanrequiredapproval_requiredbooleanrequiredapproval_expires_atstring<date-time> | nulllegacy_provider_labelstring | nullsetup_notestring | nullIntegration
objectidintegerproviderstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollocategorystringemailsmscrmrevenueecommercedataactivebooleanprimarybooleanstatusstringpendingconnectederrorconnected_atstring<date-time> | nulllast_tested_atstring<date-time> | nullerror_messagestring | nullconfig_summaryobjectsecret_hintsobjectcreated_atstring<date-time>updated_atstring<date-time>SmtpFeedbackPayload
objecttypestringtestrequiredtypestringdeliveredbouncedcomplainedrequiredmessage_idstringrequiredOriginal RFC Message-ID, with or without surrounding angle brackets.
recipientstring<email>requiredoccurred_atstring<date-time>requiredOutcome time, no more than five minutes in the future.
statusstringRequired only for bounced events. Recipient failures suppress; policy failures remain delivery_failed observations.
nitrosend_message_idinteger<int64>[1, 9223372036854776000]Optional original X-Nitro-Message-Id, supplied together with dispatch_token to correlate an outcome before the send result is persisted.
dispatch_tokenstringOriginal X-Nitro-Dispatch header, supplied together with nitrosend_message_id.
SmtpFeedbackSetup
objecturlstring<uri>requiredsigning_secretstringrequiredConnection-specific whsec_ key; never included in integration lists or broadcasts.
signing_formatstringstandard_webhooksrequiredeventsArray<object>requiredIntegrationWriteRequest
objectintegrationMailgunIntegrationInput | SesIntegrationInput | PostmarkIntegrationInput | ResendIntegrationInput | SendgridIntegrationInput | ActiveCampaignIntegrationInputrequiredIntegrationSyncContract
objectversioninteger1requiredmirror_listsbooleanrequiredupdated_atstring<date-time> | nullIntegrationSyncObjectSelection
objectobject_idstringobject_slugstringrequiredlabelstringmodestringaddressablerelatedrequiredenabledbooleantruefield_policystringall_supportedselectedselected_fieldsArray<string>excluded_fieldsArray<string>relationshipobjecttrait_mappingIntegrationSyncTraitMappingmanaged_audience_mapping_keystringmirror_listsbooleanIntegrationSyncTraitMapping
objectkindstringdeal_pipelinerequiredstage_attributestringrequiredclosed_stage_valuesArray<string>requiredamount_attributestringcurrency_attributestringIntegrationSyncDiscovery
objectproviderstringrequiredversioninteger1requiredtruncatedbooleanrequiredobjectsArray<object>requiredIntegrationSyncDiscoveredAttribute
objectattribute_idstringrequiredattribute_slugstringrequiredtitlestringtypestringrequiredclassificationstringcanonical_scalarfact_onlyrelationshiprequiredrequiredbooleanuniquebooleanmultiselectbooleantarget_object_slugsArray<string>optionsArray<string>MailgunIntegrationInput
objectproviderstringmailgunrequiredapi_keystringrequireddomainstringrequiredMailgun sending domain
regionstring | nullOptional Mailgun region hint
activebooleantrueSesIntegrationInput
objectproviderstringsesrequiredaccess_key_idstringrequiredsecret_access_keystringrequiredregionstringrequiredAWS SES region
activebooleantruePostmarkIntegrationInput
objectproviderstringpostmarkrequiredserver_tokenstringrequiredPostmark server token for sending email
account_tokenstringrequiredPostmark account token for domains API access
activebooleantrueActiveCampaignIntegrationInput
objectproviderstringactivecampaignrequiredapi_urlstring<uri>requiredThe API URL from ActiveCampaign Settings > Developer, like https://youraccount.api-us1.com. Only https on an ActiveCampaign API host is accepted.
api_keystringrequiredwrite onlyactivebooleantruePlan
objectidintegernamestringactivebooleanchange_timingstring | nullimmediaterenewalAvailable on account-scoped base offers; uses the same rule as subscription change scheduling.
change_atstring<date-time> | nullchange_blockersArray<object>Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.
probation_recipient_cap_24hinteger>= 0Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.
standard_recipient_cap_24hinteger>= 0trusted_recipient_cap_24hinteger>= 0Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.
entitlementsBillingEntitlementsEmailDesign
objectEmail template design document
versionversion>= 1sectionsArray<EmailSection>themethemeTheme overrides merged on top of brand theme
EmailAccessibilityLint
objectAdvisory accessibility lint result for rendered email previews
product_bindingsArray<object>validbooleanAlways true while accessibility lint is advisory-only
warningsArray<EmailAccessibilityWarning>EmailAccessibilityWarning
objectlevelstringwarningrulestringimage_alt_textmessagestringsuggested_fixstringcountintegermin_rationumber<float>EmailSection
objectbindingobjectProduct sections only. An event path (event.*) is a pure projection from the original flow trigger event at send time; product binds an object or an explicit array index; products/gallery require limit (1–50); campaign drafts require fixed products for event paths, and reusable templates may retain them for flows; no expression evaluation. A products grid may instead bind catalog.best_sellers or catalog.new_arrivals with a limit (1–50), in campaigns and flows. Nitrosend fills its items from the brand's synced Shopify catalog each time the email's content is saved (best sellers rank paid orders from the last 30 days and top up with new arrivals; only active products with a link); nothing is looked up at send time. Flow emails also refresh once a day under the account's agent rules (with Safe Mode on, a person publishes the refresh), except flows with an A/B split, which keep the products from their last save, and flows with a change waiting to be published, which refresh again once it is published or replaced. Bound grids/galleries are top-level. Empty event arrays render nothing. A catalog grid with no products to show saves empty, and publishing or sending the email is refused until the email is edited and saved again with products in the catalog, or the binding is removed for fixed items; the daily refresh never empties a grid and keeps its current products instead. Missing names/actual links and unsafe values fail validation.
blockobjectTop-level sections only. Links the section to a block, a library template (flow_id null) of the same brand. Each save writes the block's current sections in its place, each carrying this link and the key naming that occurrence; a link without a key is given one. Editing the block re-saves every email linking it, and live flows publish the change under the account's agent rules (with Safe Mode on, a person publishes it). A flow with a change waiting to be published or an A/B split gets the change in its draft instead, and a campaign changes only while it is an unapproved draft. Changes sent in linked sections are written over (a block with no sections leaves them as sent); to change one email's copy on its own, remove block from its sections. A link to anything else is dropped and its sections are kept; library templates keep no links.
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequiredpropsobjectSection-specific properties (see email component spec)
stylesobjectEmailComponentSpec
objectFull schema for email design sections. Each component has type, description, props (with types, required flags, defaults), and tips.
versionintegerrequireddesign_guidelinesstringrequiredrenderer_versionstringrequiredThe @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.
componentsArray<object>requiredstyle_attributesArray<object>requiredStandard per-section style attribute registry.
preview_documentobjectrequiredvariablesobjectrequiredMerge variables grouped by source namespace.
filtersArray<object>requiredtheme_attributesArray<object>requiredBrand Kit theme attribute registry (single source of truth for the editor).
FlowSpec
objectSchema for flow step types, trigger events, and segment filter names. Each trigger's variables.filters declares current-event attribute filters available only in that trigger's flow splits. Use the normal attribute shape, for example name: event.plan_pitch_allowed, predicate: true, value: true. Top-level filters remain ordinary audience/history filters. Note: the raw response includes internal fields (icon, visible, inputs, outputs, alias) used by the flow editor UI — these can be ignored by API consumers.
filtersfilterstriggersArray<object>filter_limitsobjectLimits every filter tree is held to on save. A tree past either limit is refused with invalid_filter.
stepsArray<object>