Nitrosend API

v1.1.6
Base URLs
https://api.nitrosend.comProduction
http://localhost:8000Local development

Multi-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:

  1. API Key — Authorization: Bearer nskey_live_...
  2. JWT — Authorization: Bearer <jwt> (obtained from POST /v1/login)
  3. Shopify ID token — supplied by App Bridge for an installed embedded app
  4. Management credential — Authorization: Bearer nsmc_live_..., pinned to one managed account and brand under the existing operator_v1 policy. Domain receiving setup and dashboard webhooks use domain.read/manage and integration.read/manage respectively. 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 records
  • X-Total-Pages — total pages
  • X-Page-Number — current page
  • X-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

BearerAuthhttp

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.

Scheme: bearer

PartnerProvisioningCredentialhttp

Manager-account provisioning credential revealed once at issuance.

Scheme: bearer (nspk_live)

ManagementCredentialhttp

One-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

POST
https://api.nitrosend.com/v1/signup

Body

application/json
userobjectrequired
Show child attributes
first_namestring
last_namestring
emailstring<email>required
mobilestring
invite_tokenstring | null
referral_codestring | null

Partner or referral code. The signup succeeds even when the code is invalid; the outcome is reported in meta.promo.

rewardful_referral_idstring | null
signup_intentSignupIntent | nullagency

Optional. 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.

passwordstring<password>required
password_confirmationstring<password>
attribution_contextFirstTouchAttributionContext

Optional 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.

Show child attributes
landing_urlstring | null
referrer_urlstring | null
captured_atstring<date-time> | null
utm_sourcestring | null
utm_mediumstring | null
utm_campaignstring | null
utm_contentstring | null
utm_termstring | null
fbclidstring | null

Meta click identifier (fbclid) from the first touch, subject to the click-identifier rules above.

ttclidstring | null

TikTok click identifier (ttclid) from the first touch, subject to the click-identifier rules above.

Parameters

X-Nitrosend-Device-Typestringcomputerphonetabletheader

Bounded client-declared signup measurement; never authentication or account authority. OAuth preserves it through the existing signed attribution context.

X-Nitrosend-In-App-BrowserstringInstagramFacebookTikTokLinkedInXGoogle appthis appheader

Bounded 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.

Response fields application/json
statusstringverification_requiredrequired
error_codestringverification_required
next_actionstringverify_emailrequired
messagestringrequired
errorboolean
codeinteger
verification_expires_ininteger
Example
1800
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
429Too Many Requestsobject

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.

Response headers
Retry-Afterinteger>= 1header

Seconds before retrying

Response fields application/json
error_codestringsignup_capacity_reached
messagestring
next_actionstring
503Service Unavailable

Signup paused or mail could not be queued. Retry later.

Request an email verification link

POST
https://api.nitrosend.com/v1/signup/resend

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

application/json
emailstring<email>required

Response

If eligible, verification mail is queued. No credential is returned.

Response fields application/json
statusstringverification_requiredrequired
error_codestringverification_required
next_actionstringverify_emailrequired
messagestringrequired
errorboolean
codeinteger
verification_expires_ininteger
Example
1800
429Too Many Requestsobject

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.

Response headers
Retry-Afterinteger>= 1header

Seconds before retrying

Response fields application/json
error_codestringsignup_capacity_reached
messagestring
next_actionstring
503Service Unavailable

Mail could not be queued. Retry later.

Prove email ownership and complete signup

POST
https://api.nitrosend.com/v1/signup/verify

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

application/json
tokenstring<password>requiredwrite only
passwordstring<password>write only

Required to complete a new password signup.

Response

200OKUser & object | object

Signup complete, or an established email change confirmed.

Response headers
Authorizationstringheader

Bearer JWT only after successful signup activation. Absent for email changes.

Response fields application/json
One of
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>
metaobject
Show child attributes
account_idinteger | null
Show child attributes
appliedbooleanrequired

Whether the code was redeemed.

reasonstringappliedblanknot_foundnot_redeemableplan_not_foundpartner_access_revokedrequired
partnerbooleanrequired

True when the code made the account a partner (Affiliates tab and Client Management). Partner codes never change the plan.

plan_grantedbooleanrequired

True only when a referral code granted a plan.

plan_pendingboolean

True when an optional partner plan offer is being applied after signup.

statusstringemail_verifiedrequired
next_actionstringsign_inrequired
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
429Too Many Requestsobject

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.

Response headers
Retry-Afterinteger>= 1header

Seconds before retrying

Response fields application/json
error_codestringsignup_capacity_reached
messagestring
next_actionstring
503Service Unavailable

Proof may already be saved. Retry activation with email and final password.

Resume an already verified signup

POST
https://api.nitrosend.com/v1/signup/activate

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

application/json
emailstring<email>required
passwordstring<password>requiredwrite only

Response

Active session

Response headers
Authorizationstringheader

Bearer JWT for the session

Response fields application/json
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>
metaobject
Show child attributes
account_idinteger | null
Show child attributes
appliedbooleanrequired

Whether the code was redeemed.

reasonstringappliedblanknot_foundnot_redeemableplan_not_foundpartner_access_revokedrequired
partnerbooleanrequired

True when the code made the account a partner (Affiliates tab and Client Management). Partner codes never change the plan.

plan_grantedbooleanrequired

True only when a referral code granted a plan.

plan_pendingboolean

True when an optional partner plan offer is being applied after signup.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
429Too Many Requestsobject

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.

Response headers
Retry-Afterinteger>= 1header

Seconds before retrying

Response fields application/json
error_codestringsignup_capacity_reached
messagestring
next_actionstring
503Service Unavailable

Activation could not finish. Retry with the same email and final password.

Sign in and receive a JWT

POST
https://api.nitrosend.com/v1/login

Body

application/json
userobjectrequired
Show child attributes
emailstring<email>required
passwordstring<password>required

Response

200OKUser & object

Signed in

Response headers
Authorizationstringheader

JWT token

Response fields application/json
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>
metaobject

Present when the user has an account.

Show child attributes
account_idinteger

The account this sign-in opens on. Send it as X-Account-ID to act on that account.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

The user has no account yet and their email domain is not eligible for signup. No account is created, and no session or token is issued.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Sign out and revoke JWT

DELETE
https://api.nitrosend.com/v1/logout

Response

204No Content

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

GET
https://api.nitrosend.com/v1/oauth/me

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_idstringquery

OAuth application ID, used to name the connection being authorized.

Response

Popup context

Response fields application/json
application_namestring | null
emailstring

The signed-in person's address, where an agent's first test goes.

accountsArray<OAuthPopupAccount>required
Show child attributes
idintegerrequired
namestringrequired
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
can_manageboolean
has_campaignboolean

Whether the account has made any campaign. This alone does not determine onboarding eligibility.

setup_brandobject | null

Optional 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.

Show child attributes
sidstringrequired
suggested_sitestring | null
brand_colorstringrequired
needs_subscribebooleanrequired

Offers available through this account's provider, including retained Free terms when eligible.

Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
Show child attributes
idintegerrequired
namestringrequired
slugstringrequired
base_price_centsintegerrequired
intervalstring | null
tier_groupstring
stripe_publishable_keystring | null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403Forbiddenobject

The user has no account yet and their email domain is not eligible for signup, so none is created.

Response fields application/json
errorstringrequired

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

POST
https://api.nitrosend.com/v1/oauth/subscribe

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

application/json
plan_idintegerrequired
account_idinteger | null
stripe_tokenstring | null

Response

Popup can continue to consent

Response fields application/json
next_stepstringconsentrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403Forbiddenobject

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.

Response fields application/json
errorstringrequired
billing_routeobject

Present when the account bills through another provider.

422Unprocessable Entityobject

Account or plan selection failed

Response fields application/json
errorstringrequired

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

POST
https://api.nitrosend.com/v1/oauth/launch

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

application/json
providerstringgoogle_oauth2githubrequired
auth_intentstringappagentapp
auth_stepstringloginsignuplogin
resume_urlstring<uri> | null

Required when auth_intent=agent; must point to the frontend /oauth/connect route.

invite_tokenstring | null
referral_codestring | null
rewardful_referral_idstring | null
attribution_contextFirstTouchAttributionContext

Optional 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.

Show child attributes
landing_urlstring | null
referrer_urlstring | null
captured_atstring<date-time> | null
utm_sourcestring | null
utm_mediumstring | null
utm_campaignstring | null
utm_contentstring | null
utm_termstring | null
fbclidstring | null

Meta click identifier (fbclid) from the first touch, subject to the click-identifier rules above.

ttclidstring | null

TikTok click identifier (ttclid) from the first touch, subject to the click-identifier rules above.

signup_intentSignupIntent | nullagency

Optional. 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-Typestringcomputerphonetabletheader

Bounded client-declared signup measurement; never authentication or account authority. OAuth preserves it through the existing signed attribution context.

X-Nitrosend-In-App-BrowserstringInstagramFacebookTikTokLinkedInXGoogle appthis appheader

Bounded client-declared embedded browser measurement. Omitted or unknown is unclassified, not proof of a standalone browser.

Response

Launch URL created

Response fields application/json
launch_urlstring<uri>required
400Bad Requestobject

Invalid provider or resume URL

Response fields application/json
errorstringrequired

Sign in with a one-time link

POST
https://api.nitrosend.com/v1/sign_in_links/consume

Body

application/json
tokenstringrequired

Response

200OK

A session token and the account and brand to open

404Not Found

Not a link we issued

410Gone

Expired or already used

Send a fresh link to the owner of an expired one

POST
https://api.nitrosend.com/v1/sign_in_links/resend

Always answers 202, and sends only to the account's own address, so it says nothing about whether the token named an account.

Body

application/json
tokenstringrequired

Response

202Accepted

Accepted

User

Current user profile

Get current user profile

GET
https://api.nitrosend.com/v1/my/user

Response

200OKUser

User profile

Response fields application/json
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update current user profile

PATCH
https://api.nitrosend.com/v1/my/user

Body

application/json
first_namestring
last_namestring
emailstring | Array<string>
Show child attributes
One of
string<email>
Array<string>
mobilestring
time_zonestring | null

Response

200OKUser

Updated user

Response fields application/json
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/impersonation

Response

Current impersonation state

Response fields application/json
impersonatingbooleanrequired
impersonatorImpersonator | nullrequired
Show child attributes
One of
idinteger
emailstring<email>
namestring | null
null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Revoke the active impersonation session

DELETE
https://api.nitrosend.com/v1/my/impersonation

Response

Impersonation session revoked

Response fields application/json
redirect_urlstring<uri>required
Example
https://api.nitrosend.com/adm
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Account

Account settings and configuration

Get account details

GET
https://api.nitrosend.com/v1/my/account

Response

200OKAccount

Account with billing. Brands are listed by GET /v1/my/brands.

Response fields application/json
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>

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

PATCH
https://api.nitrosend.com/v1/my/account

Body

application/json
namestring
avatarstring

Signed blob ID

bannerstring

Signed blob ID

Response

200OKAccount

Updated account

Response fields application/json
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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)

GET
https://api.nitrosend.com/v1/my/accounts

Parameters

pageinteger1query
perinteger<= 100100query

Response

Accessible accounts

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>

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

GET
https://api.nitrosend.com/v1/my/account/management_grant

Only the canonical owner of the selected managed account may use this endpoint.

Response

Current management grant

Response fields application/json
idintegerrequired
statusstringpendingactiverevokedreleasedrequired
permission_setstringoperator_v1required
manager_accountobjectrequired
Show child attributes
idintegerrequired
namestring | null
requested_atstring<date-time>required
activated_atstring<date-time> | null
revoked_atstring<date-time> | null
released_atstring<date-time> | null
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Reconcile a consented, paid managed-account grant

POST
https://api.nitrosend.com/v1/my/account/management_grant/confirm

This endpoint cannot record owner consent or bypass paid activation.

Body

application/json
management_grant_idintegerrequired

Exact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.

Response

Active management grant

Response fields application/json
idintegerrequired
statusstringpendingactiverevokedreleasedrequired
permission_setstringoperator_v1required
manager_accountobjectrequired
Show child attributes
idintegerrequired
namestring | null
requested_atstring<date-time>required
activated_atstring<date-time> | null
revoked_atstring<date-time> | null
released_atstring<date-time> | null
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

The grant cannot transition from its current state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Revoke an exact pending or active management grant

POST
https://api.nitrosend.com/v1/my/account/management_grant/revoke

Revocation takes effect on the next REST or MCP request and is idempotent for the exact grant.

Body

application/json
management_grant_idintegerrequired

Exact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.

Response

Revoked management grant

Response fields application/json
idintegerrequired
statusstringpendingactiverevokedreleasedrequired
permission_setstringoperator_v1required
manager_accountobjectrequired
Show child attributes
idintegerrequired
namestring | null
requested_atstring<date-time>required
activated_atstring<date-time> | null
revoked_atstring<date-time> | null
released_atstring<date-time> | null
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

The grant cannot transition from its current state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get team metadata for the current account

GET
https://api.nitrosend.com/v1/my/account/team

Response

Team metadata

Response fields application/json
accountAccount
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>
Show child attributes
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>
Show child attributes
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
accessible_accountsArray<Account>
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>

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

GET
https://api.nitrosend.com/v1/my/account/reach

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>= 1requiredquery

Number of recipients of one full send

Response

Reach on the current plan and the recommended plan

Response fields application/json
audienceintegerrequired
cohortstringrequired

The account's deliverability cohort the daily caps are read at

currentAudienceReachFit | null

The current plan; null when the account has no subscription

Show child attributes
plan_idintegerrequired
slugstringrequired
namestringrequired
tier_groupstringrequired
daily_capinteger | null

Recipients per 24 hours at the account's sending standing; null when unlimited

capacityinteger | null

Emails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited

days_to_reachinteger | null

Days until everyone has been reached once; null when the month cannot hold the send

coversbooleanrequired

Whether one full send to the audience fits within the month

recommendedAudienceReachFit | null

The 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

Show child attributes
plan_idintegerrequired
slugstringrequired
namestringrequired
tier_groupstringrequired
daily_capinteger | null

Recipients per 24 hours at the account's sending standing; null when unlimited

capacityinteger | null

Emails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited

days_to_reachinteger | null

Days until everyone has been reached once; null when the month cannot hold the send

coversbooleanrequired

Whether one full send to the audience fits within the month

coveredbooleanrequired

Whether the current plan covers a full send

summarystring | null

The one sentence every surface shows; null when covered

422Unprocessable EntityError

audience is not a positive whole number (error_code audience_invalid)

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

List account memberships (paginated)

GET
https://api.nitrosend.com/v1/my/account/memberships

Parameters

pageinteger1query
perinteger<= 100100query

Response

Memberships

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>

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

DELETE
https://api.nitrosend.com/v1/my/account/memberships/{id}

Parameters

idintegerrequiredpath

Response

Removed membership

Response fields application/json
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>

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

PATCH
https://api.nitrosend.com/v1/my/account/memberships/{id}

Body

application/json
rolestringmemberadmin

Parameters

idintegerrequiredpath

Response

Updated membership

Response fields application/json
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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)

GET
https://api.nitrosend.com/v1/my/account/invites

Parameters

pageinteger1query
perinteger<= 100100query

Response

Invites

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/account/invites

Body

application/json
emailstring<email>required
rolestringmemberadmin

Response

201CreatedAccountInvite

Created invite

Response fields application/json
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

DELETE
https://api.nitrosend.com/v1/my/account/invites/{id}

Parameters

idintegerrequiredpath

Response

Revoked invite

Response fields application/json
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/account/invites/{id}/accept

Parameters

idstringrequiredpath

Response

Accepted invite

Response fields application/json
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/affiliate

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

Response fields application/json
enrolledbooleanrequired

Whether the account is linked to a Rewardful affiliate.

availablebooleanrequired

Whether live affiliate data or setup is currently available.

statestring | nullactivepausedunavailable
setup_statusstring | nullpendingneeds_detailsunavailable

Present only while an entitled, unlinked account is being reconciled.

share_urlstring<uri> | null
statsobject
Show child attributes
visitorsinteger>= 0
leadsinteger>= 0
conversionsinteger>= 0
earningsobject
Show child attributes
knownboolean
total_centsinteger | null
currencystring
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Reconcile the current account's affiliate immediately

POST
https://api.nitrosend.com/v1/my/affiliate

Session/JWT-only repair path. This is idempotent and uses the same existing-or-create behavior as background reconciliation.

Body

application/json
first_namestring
last_namestring

Response

Existing or already-linked affiliate

Response fields application/json
enrolledbooleanrequired

Whether the account is linked to a Rewardful affiliate.

availablebooleanrequired

Whether live affiliate data or setup is currently available.

statestring | nullactivepausedunavailable
setup_statusstring | nullpendingneeds_detailsunavailable

Present only while an entitled, unlinked account is being reconciled.

share_urlstring<uri> | null
statsobject
Show child attributes
visitorsinteger>= 0
leadsinteger>= 0
conversionsinteger>= 0
earningsobject
Show child attributes
knownboolean
total_centsinteger | null
currencystring

Affiliate identity linked to the account

Response fields application/json
enrolledbooleanrequired

Whether the account is linked to a Rewardful affiliate.

availablebooleanrequired

Whether live affiliate data or setup is currently available.

statestring | nullactivepausedunavailable
setup_statusstring | nullpendingneeds_detailsunavailable

Present only while an entitled, unlinked account is being reconciled.

share_urlstring<uri> | null
statsobject
Show child attributes
visitorsinteger>= 0
leadsinteger>= 0
conversionsinteger>= 0
earningsobject
Show child attributes
knownboolean
total_centsinteger | null
currencystring
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
503Service UnavailableError

Upstream service unavailable

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Managed Clients

Explicitly enabled client provisioning, consent, and portfolio operations

List the selected manager account's client portfolio

GET
https://api.nitrosend.com/v1/my/managed_accounts

Parameters

pageinteger1query
perinteger<= 10025query
qstringquery
statusManagedAccountLifecycleStatusFilterquery

Use needs_setup to group preparing, awaiting owner, payment required, and payment issue rows.

sortstringcreated_atnameowner_emailstatuscreated_atquery
directionstringascdescdescquery

Response

Bounded managed-client portfolio

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Provision a paid-required, client-owned account

POST
https://api.nitrosend.com/v1/my/managed_accounts

Body

application/json
managed_accountobjectrequired
Show child attributes
owner_emailstring<email>required
owner_first_namestring
owner_last_namestring
account_namestringrequired

Parameters

Idempotency-Keystringrequiredheader

Exact-request idempotency key; changed normalized input conflicts.

Response

Exact idempotent replay

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
idempotent_replaybooleanrequired

Client provisioned in preparing state; no owner invitation has been sent

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
idempotent_replaybooleanrequired
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/managed_accounts/{id}

Parameters

idintegerrequiredpath

Response

Managed-client portfolio row

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Invalidate the prior invitation and queue a bounded replacement for owner-only delivery

POST
https://api.nitrosend.com/v1/my/managed_accounts/{id}/resend_invitation

Parameters

idintegerrequiredpath

Response

Updated portfolio row; no invitation capability is returned

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Queue the first bounded owner invitation after client setup is ready

POST
https://api.nitrosend.com/v1/my/managed_accounts/{id}/send_invitation

Parameters

idintegerrequiredpath

Response

Updated portfolio row; no invitation capability is returned

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Queue a cooldown-bound payment reminder to the owner

POST
https://api.nitrosend.com/v1/my/managed_accounts/{id}/payment_reminder

Parameters

idintegerrequiredpath

Response

204No Content

Reminder accepted for delivery

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

End the selected manager's relationship with the client

POST
https://api.nitrosend.com/v1/my/managed_accounts/{id}/release

Parameters

idintegerrequiredpath

Response

Ended managed-client relationship

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

List non-secret provisioning credential metadata

GET
https://api.nitrosend.com/v1/my/account/provisioning_credentials

Response

Provisioning credential metadata

Response fields application/json
Show child attributes
idintegerrequired
namestringrequired
scopesArray<string>provisionmanagerequired
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Issue a provisioning credential and reveal its secret once

POST
https://api.nitrosend.com/v1/my/account/provisioning_credentials

Body

application/json
credentialobjectrequired
Show child attributes
namestringrequired
scopesArray<string>provisionmanagerequired
expires_atstring<date-time>

Response

One-time credential result

Response headers
Cache-Controlstringheader

Always includes no-store

Response fields application/json
idintegerrequired
namestringrequired
scopesArray<string>provisionmanagerequired
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

DELETE
https://api.nitrosend.com/v1/my/account/provisioning_credentials/{id}

Parameters

idintegerrequiredpath

Response

Revoked credential metadata

Response fields application/json
idintegerrequired
namestringrequired
scopesArray<string>provisionmanagerequired
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Inspect a bounded owner consent capability

POST
https://api.nitrosend.com/v1/managed_account_claims/inspect

Body

application/json
claimobjectrequired
Show child attributes
tokenstringrequiredwrite only

Response

Bounded claim projection

Response fields application/json
managerobjectrequired
Show child attributes
namestring | null
managed_accountobjectrequired
Show child attributes
namestring | null
owner_emailstringrequired

Masked owner address

expires_atstring<date-time>required
authenticationstringrequired
410GoneError

One-time capability is invalid, expired, rotated, or consumed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Record one-time consent for the exact authenticated owner

POST
https://api.nitrosend.com/v1/managed_account_claims/complete

Body

application/json
claimobjectrequired
Show child attributes
tokenstringrequiredwrite only

Response

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

Response headers
Cache-Controlstringheader

Always includes no-store

Response fields application/json
claimedbooleanrequired
statusstringpayment_requiredactivemanager_disabledrequired

The agency's management access. active on Setup mode does not mean paid; read payment_required.

payment_requiredbooleanrequired

The 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_setupbooleanrequired

The client account is on Setup mode.

managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

410GoneError

One-time capability is invalid, expired, rotated, or consumed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/partner/managed_accounts

Response

Managed-client portfolio

Response fields application/json
Show child attributes
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Provision a paid-required client-owned account

POST
https://api.nitrosend.com/v1/partner/managed_accounts

Body

application/json
managed_accountobjectrequired
Show child attributes
external_refstringrequired
owner_emailstring<email>required
owner_first_namestring
owner_last_namestring
account_namestringrequired

Parameters

Idempotency-Keystringrequiredheader

Exact-request idempotency key; changed normalized input conflicts.

Response

Exact idempotent replay

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
idempotent_replaybooleanrequired

Client provisioned in preparing state; no owner invitation has been sent

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
idempotent_replaybooleanrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Get one manager-scoped portfolio row

GET
https://api.nitrosend.com/v1/partner/managed_accounts/{id}

Parameters

idintegerrequiredpath

Response

Managed-client portfolio row

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Invalidate the prior invitation and queue a bounded replacement for owner-only delivery

POST
https://api.nitrosend.com/v1/partner/managed_accounts/{id}/resend_invitation

Parameters

idintegerrequiredpath

Response

Updated portfolio row; no invitation capability is returned

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Queue the first bounded owner invitation after client setup is ready

POST
https://api.nitrosend.com/v1/partner/managed_accounts/{id}/send_invitation

Parameters

idintegerrequiredpath

Response

Updated portfolio row; no invitation capability is returned

Response fields application/json
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

List non-secret agent credential metadata for one managed client

GET
https://api.nitrosend.com/v1/partner/managed_accounts/{provisioning_id}/credentials

Parameters

provisioning_idintegerrequiredpath

Manager-scoped provisioning row id.

Response

Agent credential metadata; plaintext secrets are never listed

Response fields application/json
Show child attributes
idintegerrequired
account_management_grant_idintegerrequired
namestringrequired
permission_setstringoperator_v1required
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
brandobjectrequired
Show child attributes
idintegerrequired
sidstringrequired
namestringrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Issue one grant- and Brand-pinned agent credential

POST
https://api.nitrosend.com/v1/partner/managed_accounts/{provisioning_id}/credentials

Body

application/json
credentialobjectrequired
Show child attributes
namestringrequired
brand_sidstring

Defaults to the managed Account's default Brand.

expires_atstring<date-time>

Defaults to 90 days and cannot exceed one year.

Parameters

provisioning_idintegerrequiredpath

Manager-scoped provisioning row id.

Response

One-time credential result; the secret cannot be recovered

Response headers
Cache-Controlstringheader

Always includes no-store

Response fields application/json
idintegerrequired
account_management_grant_idintegerrequired
namestringrequired
permission_setstringoperator_v1required
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
brandobjectrequired
Show child attributes
idintegerrequired
sidstringrequired
namestringrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Revoke one agent credential immediately

DELETE
https://api.nitrosend.com/v1/partner/managed_accounts/{provisioning_id}/credentials/{id}

Parameters

provisioning_idintegerrequiredpath

Manager-scoped provisioning row id.

idintegerrequiredpath

Response

Revoked credential metadata

Response fields application/json
idintegerrequired
account_management_grant_idintegerrequired
namestringrequired
permission_setstringoperator_v1required
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
brandobjectrequired
Show child attributes
idintegerrequired
sidstringrequired
namestringrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Authorization

PartnerProvisioningCredentialhttp (bearer)

Manager-account provisioning credential revealed once at issuance.

Billing

Subscription billing and checkout

Download an account invoice

GET
https://api.nitrosend.com/v1/my/invoices/{id}/download

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

idintegerrequiredpath

Response

200OKstring<binary>

Original invoice PDF

Response fields application/pdf
string<binary>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Invoice not found in the current account, ownership cannot be verified, or no Stripe PDF is available

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

500Internal Server ErrorError

The invoice document could not be retrieved

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Ask the Nitrosend team about Enterprise

POST
https://api.nitrosend.com/v1/my/enterprise_requests

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

application/json
monthly_emailsinteger | string | null

Emails 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.

Show child attributes
One of
integer[0, 1000000000]
string
null
needsArray<string> | nullvolume_pricingdedicated_ipseats_or_domainssecurity_reviewinvoicingmigration
messagestring | null

Response

This member already sent a request today; the receipt is for that request

Response fields application/json
receivedbooleanrequired
replayedbooleanrequired

True when this is the member's request from earlier today.

requestobjectrequired
Show child attributes
idintegerrequired
received_atstring<date-time>required
requester_emailstring<email>required

Where the team will reply.

Request received

Response fields application/json
receivedbooleanrequired
replayedbooleanrequired

True when this is the member's request from earlier today.

requestobjectrequired
Show child attributes
idintegerrequired
received_atstring<date-time>required
requester_emailstring<email>required

Where the team will reply.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

A field has the wrong shape or is out of range (error_code enterprise_request_invalid, with validation_errors per field).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
503Service UnavailableError

The request could not be sent to the team, so it was not kept (error_code enterprise_request_unrecorded); email contact@nitrosend.com instead.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Read the current subscription

GET
https://api.nitrosend.com/v1/my/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

200OKSubscription | DelegatedSubscription | null

The current subscription, or null when the account has none

Response fields application/json
Any of
idinteger
plan_idinteger
plan_namestring | null

Current package name. Historical purchase labels are retained in billing records.

billing_providerstring | nullshopifystripestripe_projectsvercelaws
source_billing_providerstring | nullshopifystripestripe_projectsvercelaws
billing_migration_requiredboolean
manage_urlstring<uri> | null
spend_cap_monthly_centsinteger | null>= 0

Merchant-selected monthly cap for metered usage charges.

shopify_usage_meteredboolean

Whether the active Shopify plan has at least one configured usage meter.

statusstringpendingactiveinactivecanceledfree_tier
intervalstringmonthyearweekday
currencystring
subtotal_centsinteger
tax_centsinteger
total_centsinteger
base_price_centsinteger
discount_centsinteger

Per-period Stripe discount in cents (0 when none).

next_payment_centsinteger

Amount billed next period

discount_end_atstring<date-time> | null

When the discount stops (null for forever/once or no discount).

activatedboolean
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

What 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.

idintegerrequired
plan_idintegerrequired
plan_namestring | nullrequired
statusstringpendingactiveinactivecanceledfree_tierrequired
intervalstringmonthyearweekdayrequired
currencystringrequired
activatedbooleanrequired
base_price_centsintegerrequired
billing_providerstring | nullshopifystripestripe_projectsvercelawsrequired
source_billing_providerstring | nullshopifystripestripe_projectsvercelawsrequired
billing_routeobjectrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Create a subscription

POST
https://api.nitrosend.com/v1/my/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

application/json
plan_idintegerrequired
stripe_tokenstring | null

Stripe card token for paid-plan creation.

coupon_codestring | null

Customer-entered Stripe promotion code or coupon ID. Refused on an agency operator's purchase for a client account.

Response

201CreatedSubscription | DelegatedSubscription

Subscription created

Response fields application/json
Any of
idinteger
plan_idinteger
plan_namestring | null

Current package name. Historical purchase labels are retained in billing records.

billing_providerstring | nullshopifystripestripe_projectsvercelaws
source_billing_providerstring | nullshopifystripestripe_projectsvercelaws
billing_migration_requiredboolean
manage_urlstring<uri> | null
spend_cap_monthly_centsinteger | null>= 0

Merchant-selected monthly cap for metered usage charges.

shopify_usage_meteredboolean

Whether the active Shopify plan has at least one configured usage meter.

statusstringpendingactiveinactivecanceledfree_tier
intervalstringmonthyearweekday
currencystring
subtotal_centsinteger
tax_centsinteger
total_centsinteger
base_price_centsinteger
discount_centsinteger

Per-period Stripe discount in cents (0 when none).

next_payment_centsinteger

Amount billed next period

discount_end_atstring<date-time> | null

When the discount stops (null for forever/once or no discount).

activatedboolean
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

What 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.

idintegerrequired
plan_idintegerrequired
plan_namestring | nullrequired
statusstringpendingactiveinactivecanceledfree_tierrequired
intervalstringmonthyearweekdayrequired
currencystringrequired
activatedbooleanrequired
base_price_centsintegerrequired
billing_providerstring | nullshopifystripestripe_projectsvercelawsrequired
source_billing_providerstring | nullshopifystripestripe_projectsvercelawsrequired
billing_routeobjectrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
403ForbiddenError

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).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

The plan is not available to this account, including Free for an agency or a client account an agency created.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

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).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

DELETE
https://api.nitrosend.com/v1/my/subscription

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

Response fields application/json
idinteger
plan_idinteger
plan_namestring | null

Current package name. Historical purchase labels are retained in billing records.

billing_providerstring | nullshopifystripestripe_projectsvercelaws
source_billing_providerstring | nullshopifystripestripe_projectsvercelaws
billing_migration_requiredboolean
manage_urlstring<uri> | null
spend_cap_monthly_centsinteger | null>= 0

Merchant-selected monthly cap for metered usage charges.

shopify_usage_meteredboolean

Whether the active Shopify plan has at least one configured usage meter.

statusstringpendingactiveinactivecanceledfree_tier
intervalstringmonthyearweekday
currencystring
subtotal_centsinteger
tax_centsinteger
total_centsinteger
base_price_centsinteger
discount_centsinteger

Per-period Stripe discount in cents (0 when none).

next_payment_centsinteger

Amount billed next period

discount_end_atstring<date-time> | null

When the discount stops (null for forever/once or no discount).

activatedboolean
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
403ForbiddenError

Billing for this account is managed by another provider (error_code manage_on_shopify or billing_provider_unavailable)

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

There is no paid plan this account can cancel here.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

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.").

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Change the current subscription plan

PUT
https://api.nitrosend.com/v1/my/subscription/change

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

application/json
plan_idintegerrequired
coupon_codestring | null

Customer-entered Stripe promotion code or coupon ID.

Response

Subscription updated

Response fields application/json
idinteger
plan_idinteger
plan_namestring | null

Current package name. Historical purchase labels are retained in billing records.

billing_providerstring | nullshopifystripestripe_projectsvercelaws
source_billing_providerstring | nullshopifystripestripe_projectsvercelaws
billing_migration_requiredboolean
manage_urlstring<uri> | null
spend_cap_monthly_centsinteger | null>= 0

Merchant-selected monthly cap for metered usage charges.

shopify_usage_meteredboolean

Whether the active Shopify plan has at least one configured usage meter.

statusstringpendingactiveinactivecanceledfree_tier
intervalstringmonthyearweekday
currencystring
subtotal_centsinteger
tax_centsinteger
total_centsinteger
base_price_centsinteger
discount_centsinteger

Per-period Stripe discount in cents (0 when none).

next_payment_centsinteger

Amount billed next period

discount_end_atstring<date-time> | null

When the discount stops (null for forever/once or no discount).

activatedboolean
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
400Bad RequestError

The change cannot be applied, including any change from Setup mode (message "Choose a plan to leave Setup mode.").

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

The plan is not available to this account, including Free for an agency or a client account an agency created.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/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

application/json
plan_idintegerrequired
product_keystringbase_planbrand_capacitydomain_capacityseat_capacityfooter_removalbase_plan
quantityinteger[1, 10000]1

Units for a quantity-based offer returned by features. Other offers require one. Bound to the idempotency key.

idempotency_keystring

Optional body form of Idempotency-Key for compatibility.

new_subscriptionbooleanfalse

The 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_codestring

A 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-Keystringheader

Optional stable retry key. The server also reuses an open same-plan checkout.

Response

200OKobject

Subscription changed without external approval

Response fields application/json
object
201Createdobject

Provider-hosted checkout created

Response fields application/json
object
403ForbiddenError

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)

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Requested plan is not available, including Free for an agency or a client account an agency created

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Another checkout is pending, the idempotency key conflicts, or (with new_subscription) the account already has another paid plan (error_code plan_checkout_pending)

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

Shopify rejected the requested billing terms, or the coupon is invalid or can't apply (validation_errors.coupon_code)

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

The billing provider could not be reached

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Reconcile and read a plan purchase

GET
https://api.nitrosend.com/v1/my/subscription/checkout_status

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_planquery
purchase_idintegerquery

Response

200OKobject

Reconciled plan purchase status

Response fields application/json
purchase_idinteger | null
subscription_idinteger | null
has_subscriptionbooleanrequired
statusstring | null
activatedbooleanrequired
plan_namestring | null
provider_statusstring | null
checkout_urlstring<uri> | null
approvalobject | null
billing_providerstringrequired
billing_routeobjectrequired
manage_urlstring<uri> | null
entitlementsobject | null
next_actionstring
404Not FoundError

Requested plan purchase was not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

Provider state could not be verified

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Read the current prepaid funding projection and available instruments

GET
https://api.nitrosend.com/v1/my/billing/funding

Response

Current prepaid funding status

Response fields application/json
statestringrequired
applies_tostringprepaid_featuresrequired
subscription_gatebooleanrequired
currencystringrequired
available_centsintegerrequired
reserved_centsintegerrequired
deficit_centsintegerrequired
Show child attributes
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required
pending_purchaseFundingPurchase | null
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required

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

POST
https://api.nitrosend.com/v1/my/billing/funding/purchases

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

application/json
amount_centsinteger>= 1required

Integer service value in minor currency units.

currencystring
instrumentstringstripe_checkoutshopify_one_time

Optional hosted funding instrument. Omit to use the account default.

paid_action_intent_idstring | null

Optional opaque continuation bound to this funding purchase.

Parameters

Idempotency-Keystringrequiredheader

Response

Existing idempotent funding purchase

Response fields application/json
purchaseFundingPurchaserequired
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required
fundingFundingStatusrequired
Show child attributes
statestringrequired
applies_tostringprepaid_featuresrequired
subscription_gatebooleanrequired
currencystringrequired
available_centsintegerrequired
reserved_centsintegerrequired
deficit_centsintegerrequired
Show child attributes
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required
pending_purchaseFundingPurchase | null
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required

Funding purchase created

Response fields application/json
purchaseFundingPurchaserequired
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required
fundingFundingStatusrequired
Show child attributes
statestringrequired
applies_tostringprepaid_featuresrequired
subscription_gatebooleanrequired
currencystringrequired
available_centsintegerrequired
reserved_centsintegerrequired
deficit_centsintegerrequired
Show child attributes
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required
pending_purchaseFundingPurchase | null
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required
409ConflictError

Idempotency key was used for different funding input

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

Amount or selected funding instrument is unavailable

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Read an account-scoped funding purchase

GET
https://api.nitrosend.com/v1/my/billing/funding/purchases/{id}

Parameters

idstringrequiredpath

Local purchase ID or opaque Stripe Checkout Session ID

Response

Funding purchase status

Response fields application/json
purchaseFundingPurchaserequired
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required
fundingFundingStatusrequired
Show child attributes
statestringrequired
applies_tostringprepaid_featuresrequired
subscription_gatebooleanrequired
currencystringrequired
available_centsintegerrequired
reserved_centsintegerrequired
deficit_centsintegerrequired
Show child attributes
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required
pending_purchaseFundingPurchase | null
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required
404Not FoundError

Funding purchase not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Preview a promotion code or coupon for a subscription plan

POST
https://api.nitrosend.com/v1/my/subscription/coupon_preview

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

application/json
plan_idintegerrequired
coupon_codestringrequired

Customer-entered Stripe promotion code or coupon ID.

Response

Coupon preview

Response fields application/json
codestringrequired
discount_labelstringrequired
discount_centsintegerrequired
subtotal_centsintegerrequired
tax_centsintegerrequired
total_centsintegerrequired
total_after_discount_centsintegerrequired
currencystringrequired
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/user/payment_method

Account administrator required. Reads actual provider subscription defaults; never returns payer profile details or changes a shared customer default.

Response

200OKobject

Masked cards by subscription, product_key and plan_name

Response fields application/json
payment_methodsArray<object>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Replace the card on this account's current plan and paid features

PUT
https://api.nitrosend.com/v1/my/user/payment_method

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

application/json
stripe_tokenstringrequiredwrite only

Response

200OKobject

Confirmed masked cards by account subscription

Response fields application/json
payment_methodsArray<object>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

DELETE
https://api.nitrosend.com/v1/my/user/payment_method

Response

200OK

No recurring account payment method exists

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/invoices/{id}/payment

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

idintegerrequiredpath

Response

200OKobject

Ownership-verified HTTPS Stripe invoice payment URL

Response fields application/json
payment_urlstring<uri>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not Found

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

POST
https://api.nitrosend.com/v1/my/billing/paid_action_intents

Persists encrypted, operation-owned continuation state. The intent is not spend authority and never executes the operation automatically.

Body

application/json
adapter_keystringrequired
adapter_versionstringrequired
operation_idempotency_keystringrequired
state_payloadobjectrequired

Adapter-owned state, validated and encrypted before persistence.

Response

Exact idempotent replay

Response fields application/json
idstringrequired

Opaque public continuation identifier.

schemastringrequired
statusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequired
adapterobjectrequired
Show child attributes
keystringrequired
versionstringrequired
operation_idempotency_keystringrequired
original_quote_fingerprintstringrequired
current_quote_fingerprintstring
quote_changedboolean
state_payloadobject
quoteobject
expires_atstring<date-time>required
consumed_atstring<date-time> | null
cancelled_atstring<date-time> | null

Continuation created

Response fields application/json
idstringrequired

Opaque public continuation identifier.

schemastringrequired
statusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequired
adapterobjectrequired
Show child attributes
keystringrequired
versionstringrequired
operation_idempotency_keystringrequired
original_quote_fingerprintstringrequired
current_quote_fingerprintstring
quote_changedboolean
state_payloadobject
quoteobject
expires_atstring<date-time>required
consumed_atstring<date-time> | null
cancelled_atstring<date-time> | null
409ConflictError

Operation key reused with different continuation state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/billing/paid_action_intents/{id}

Parameters

idstringrequiredpath

Opaque paid-operation continuation identifier.

Response

Actor-scoped continuation with current terms

Response fields application/json
idstringrequired

Opaque public continuation identifier.

schemastringrequired
statusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequired
adapterobjectrequired
Show child attributes
keystringrequired
versionstringrequired
operation_idempotency_keystringrequired
original_quote_fingerprintstringrequired
current_quote_fingerprintstring
quote_changedboolean
state_payloadobject
quoteobject
expires_atstring<date-time>required
consumed_atstring<date-time> | null
cancelled_atstring<date-time> | null
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Cancel and scrub a paid-operation continuation

POST
https://api.nitrosend.com/v1/my/billing/paid_action_intents/{id}/cancel

Parameters

idstringrequiredpath

Opaque paid-operation continuation identifier.

Response

Cancelled continuation

Response fields application/json
idstringrequired

Opaque public continuation identifier.

schemastringrequired
statusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequired
adapterobjectrequired
Show child attributes
keystringrequired
versionstringrequired
operation_idempotency_keystringrequired
original_quote_fingerprintstringrequired
current_quote_fingerprintstring
quote_changedboolean
state_payloadobject
quoteobject
expires_atstring<date-time>required
consumed_atstring<date-time> | null
cancelled_atstring<date-time> | null
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Terminal continuation cannot be cancelled

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Mark a successfully executed paid operation consumed

POST
https://api.nitrosend.com/v1/my/billing/paid_action_intents/{id}/consume

Parameters

idstringrequiredpath

Opaque paid-operation continuation identifier.

Response

Consumed continuation

Response fields application/json
idstringrequired

Opaque public continuation identifier.

schemastringrequired
statusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequired
adapterobjectrequired
Show child attributes
keystringrequired
versionstringrequired
operation_idempotency_keystringrequired
original_quote_fingerprintstringrequired
current_quote_fingerprintstring
quote_changedboolean
state_payloadobject
quoteobject
expires_atstring<date-time>required
consumed_atstring<date-time> | null
cancelled_atstring<date-time> | null
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Continuation is not ready to consume

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delivery

Read-only plan/cohort sending allowance and pacing state

Inspect the email sending allowance and pacing

GET
https://api.nitrosend.com/v1/my/delivery/status

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

Response fields application/json
assessment_scopestringrequired
admission_statusstringalloweddeferreddeniedrequired
sending_pauseSendingPause

What 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.

Show child attributes
sending_pausedbooleantruerequired
reasonstringcritical_bounce_ratecritical_complaint_rate

Present only for an explained deliverability pause.

occurred_atstring<date-time>required
headlinestringrequired
detailstringrequired
what_to_doArray<string>

Present only for an explained deliverability pause.

request_reviewstringrequired

The instruction an agent relays to the owner.

recovery_actionsArray<object>required
Show child attributes
typestringverify_listrequest_reviewcontact_supportrequired
labelstringrequired
urlstringrequired

App link or support mailto.

commercial_capacityDeliveryCapacityrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
shared_abuse_capacitySharedAbuseCapacityrequired

Retired shared probation allowance. Status is always not_applicable; the field remains for compatibility.

Show child attributes
statusstringavailabledeferrednot_applicableunknowndegradedrequired
reason_codestring
retry_atstring<date-time>
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
pacing_stateDeliveryPacingStaterequired
Show child attributes
statusstringreadydeferredrequired
policy_versionstringrequired
queued_quantityinteger>= 0
next_dispatch_atstring<date-time>
shared_senderSharedSenderStatus
Show child attributes
statusstringreadydeferredpauseddegradedrequired
reason_codestringshared_sender_rate_limitedshared_sender_provider_backpressureshared_sender_evidence_pending
retry_atstring<date-time>
observed_atstring<date-time>required
episode_keystringrequired
labelstringrequired
detailstringrequired
recovery_actionsArray<object>required
Show child attributes
typestringconnect_domaincontact_supportrequired
labelstringrequired
urlstring<uri>required
initial_bulk_observationobject
Show child attributes
statusstringobservingdeferredrequired
reason_codestringrequired
retry_atstring<date-time>required
labelstringrequired
detailstringrequired
Show child attributes
typestringrequired
keystring
statusstringreadydeferredrequired
next_dispatch_atstring<date-time>
minimum_interval_secondsnumber>= 0required
baseline_rate_per_secondnumber>= 0
effective_rate_per_secondnumber>= 0
cooldown_reasonstring
cooldown_untilstring<date-time>
feedback_epochinteger>= 0required
blocking_controlstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacity
reason_codestring
Show child attributes
controlstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacityrequired
reason_codestringsending_pausedbrand_unavailablesender_not_readysending_capacity_reachedsignup_sending_capacity_reacheddelivery_evidence_pendingrequired
retryablebooleanrequired
retry_atstring<date-time>
retry_atstring<date-time>
observed_atstring<date-time>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Email Validation

Explicit prepaid email validation quotes and operations

Quote explicit prepaid email validation

POST
https://api.nitrosend.com/v1/my/validation_operations/quote

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

application/json
One of
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_idinteger
segment_idinteger
all_contactsboolean

All email channels in the current Brand, subject to the 100000-candidate operation bound.

quote_digeststring

Pass 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.

any
any
any
any
any
any

Response

Non-mutating validation quote

Response fields application/json
statusstringquotedneeds_fundingrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
quote_digeststringrequired
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
mutationbooleanrequired
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

The brand's latest contact list verifications

GET
https://api.nitrosend.com/v1/my/validation_operations

Newest first, contact audiences only. Use the operation_id with the show endpoint for results and the sending choice.

Parameters

limitinteger[1, 20]5query

Response

200OKobject

Latest verifications

Response fields application/json
operationsArray<object>required
Show child attributes
operation_idstringrequired
statusstringrequired
terminalbooleanrequired

The run has finished.

source_kindstringrequired
candidate_countinteger>= 0required
created_atstring<date-time>required
completed_atstring<date-time>
failure_codestring

Present when the run stopped or expired before every check finished.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Start or resume explicit prepaid email validation

POST
https://api.nitrosend.com/v1/my/validation_operations

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

application/json
One of
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_idinteger
segment_idinteger
all_contactsboolean

All email channels in the current Brand, subject to the 100000-candidate operation bound.

quote_digeststring

Pass 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.

any
any
any
any
any
any

Parameters

Idempotency-Keystringrequiredheader

Exact-request idempotency key; changed normalized input conflicts.

Response

Durable validation operation accepted or replayed

Response fields application/json
operation_idstringrequired
statusstringrequestedquotedheldexecutingpartially_committedcommittedreleasedneeds_fundingfailedrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
item_detailobjectrequired
Show child attributes
statusstringavailablecompactedrequired
compacted_atstring<date-time>
item_countinteger>= 0
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
resultsobject

Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.

Show child attributes
valid_countinteger>= 0
invalid_countinteger>= 0
disposable_countinteger>= 0
unknown_countinteger>= 0
catchall_countinteger>= 0
unconfirmedobject

Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.

Show child attributes
excluded_countinteger>= 0

Addresses this run currently holds out of sends.

sendable_countinteger>= 0

This run's unknown and catch-all addresses still in sends.

pendingboolean

The run is still leaving its unconfirmed addresses out.

kept_countinteger>= 0
kept_atstring<date-time>
can_includeboolean

Including this run's left-out addresses can be requested now.

can_leave_outboolean

Leaving this run's sendable unconfirmed addresses out can be requested now.

include_blockedboolean

Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.

Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
failure_codestring
started_atstring<date-time>
completed_atstring<date-time>
next_actionstring
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Request conflicts with durable lifecycle or idempotency state

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/validation_operations/{id}

Parameters

idstringrequiredpath

Opaque operation_id returned by the create endpoint.

Response

Current durable operation state

Response fields application/json
operation_idstringrequired
statusstringrequestedquotedheldexecutingpartially_committedcommittedreleasedneeds_fundingfailedrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
item_detailobjectrequired
Show child attributes
statusstringavailablecompactedrequired
compacted_atstring<date-time>
item_countinteger>= 0
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
resultsobject

Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.

Show child attributes
valid_countinteger>= 0
invalid_countinteger>= 0
disposable_countinteger>= 0
unknown_countinteger>= 0
catchall_countinteger>= 0
unconfirmedobject

Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.

Show child attributes
excluded_countinteger>= 0

Addresses this run currently holds out of sends.

sendable_countinteger>= 0

This run's unknown and catch-all addresses still in sends.

pendingboolean

The run is still leaving its unconfirmed addresses out.

kept_countinteger>= 0
kept_atstring<date-time>
can_includeboolean

Including this run's left-out addresses can be requested now.

can_leave_outboolean

Leaving this run's sendable unconfirmed addresses out can be requested now.

include_blockedboolean

Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.

Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
failure_codestring
started_atstring<date-time>
completed_atstring<date-time>
next_actionstring
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Keep a finished run's unknown and catch-all addresses in sends

POST
https://api.nitrosend.com/v1/my/validation_operations/{id}/keep_unconfirmed

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

idstringrequiredpath

Response

Updated operation state

Response fields application/json
operation_idstringrequired
statusstringrequestedquotedheldexecutingpartially_committedcommittedreleasedneeds_fundingfailedrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
item_detailobjectrequired
Show child attributes
statusstringavailablecompactedrequired
compacted_atstring<date-time>
item_countinteger>= 0
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
resultsobject

Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.

Show child attributes
valid_countinteger>= 0
invalid_countinteger>= 0
disposable_countinteger>= 0
unknown_countinteger>= 0
catchall_countinteger>= 0
unconfirmedobject

Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.

Show child attributes
excluded_countinteger>= 0

Addresses this run currently holds out of sends.

sendable_countinteger>= 0

This run's unknown and catch-all addresses still in sends.

pendingboolean

The run is still leaving its unconfirmed addresses out.

kept_countinteger>= 0
kept_atstring<date-time>
can_includeboolean

Including this run's left-out addresses can be requested now.

can_leave_outboolean

Leaving this run's sendable unconfirmed addresses out can be requested now.

include_blockedboolean

Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.

Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
failure_codestring
started_atstring<date-time>
completed_atstring<date-time>
next_actionstring
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409Conflict

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

POST
https://api.nitrosend.com/v1/my/validation_operations/{id}/exclude_unconfirmed

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

idstringrequiredpath

Response

Updated operation state

Response fields application/json
operation_idstringrequired
statusstringrequestedquotedheldexecutingpartially_committedcommittedreleasedneeds_fundingfailedrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
item_detailobjectrequired
Show child attributes
statusstringavailablecompactedrequired
compacted_atstring<date-time>
item_countinteger>= 0
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
resultsobject

Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.

Show child attributes
valid_countinteger>= 0
invalid_countinteger>= 0
disposable_countinteger>= 0
unknown_countinteger>= 0
catchall_countinteger>= 0
unconfirmedobject

Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.

Show child attributes
excluded_countinteger>= 0

Addresses this run currently holds out of sends.

sendable_countinteger>= 0

This run's unknown and catch-all addresses still in sends.

pendingboolean

The run is still leaving its unconfirmed addresses out.

kept_countinteger>= 0
kept_atstring<date-time>
can_includeboolean

Including this run's left-out addresses can be requested now.

can_leave_outboolean

Leaving this run's sendable unconfirmed addresses out can be requested now.

include_blockedboolean

Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.

Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
failure_codestring
started_atstring<date-time>
completed_atstring<date-time>
next_actionstring
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409Conflict

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

GET
https://api.nitrosend.com/v1/my/validation_operations/{id}/items

Parameters

idstringrequiredpath

Opaque operation_id returned by the create endpoint.

pageinteger1query
perinteger<= 10030query

Response

Paginated operation items

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idintegerrequired
contact_channel_idinteger | null
lead_idinteger | null
emailstring<email>

Current address only if it still matches the retained verification identity

provider_observed_atstring<date-time> | null
statusstringpendingexecutingbillablenot_billableprovider_unknownfailedrequired
billableboolean
providerstring
native_statusstring
verdictstring
failure_codestring
result_referenceobject
completed_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Contacts

Contact management

List contacts (paginated)

GET
https://api.nitrosend.com/v1/my/contacts

Parameters

pageinteger1query
limitinteger<= 10050query
searchstringquery

Full-text search across name, email, phone

Canonical 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_idintegerquery

Legacy shortcut for a contact_list in [id] filter.

tagstringquery

Legacy 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_atratingquery

Column 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.

directionstringascdescdescquery

Sort direction. Only applies when sort is set.

Response

Paginated contacts

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
503Service UnavailableError

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.

Response headers
Retry-Afterintegerheader

Seconds to wait before retrying.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Create a contact

POST
https://api.nitrosend.com/v1/my/contacts

Body

application/json
first_namestring
last_namestring
emailstring<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.

phonestring

E.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}.

sourcestring
country_codestring
opt_inboolean | null

Consent 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>
dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
channels_attributesArray<object>
Show child attributes
kindstringemailphone
valuestring
subscribedboolean

Response

200OKContact

Existing contact updated in place. Returned when the submitted email belongs to a contact in this brand or, with no email, when exactly one contact in this brand holds the submitted phone.

Response fields application/json
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
201CreatedContact

Contact created

Response fields application/json
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/contacts/bulk

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

application/json
action_typestringadd_to_listremove_from_listdeleteunsubscribe_emailrequired
idsArray<integer>

Required unless match is sent. Send one of ids or match.

list_idinteger

Required for add_to_list and remove_from_list.

matchobject

Delete 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.

Show child attributes
searchstring

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
list_idinteger
tagstring
sourcestring
dry_runboolean

Delete only. Returns the count and confirmation wording without deleting.

selection_digeststring

Delete with match only, and required there. The selection_digest from the dry run being confirmed.

Response

200OKobject

Action completed, or a delete dry run

Response fields application/json
affectedinteger
actionstringrequired
list_idinteger
statusstringdone
dry_runboolean
keptinteger

Delete only. Contacts kept because they are still in use, such as in email conversations or an email verification that is still running.

contact_countinteger

Delete only. Contacts selected.

selection_digeststring

Delete dry run only. Send it back to confirm a match delete.

messagestring

Delete only. What happened or will happen

202Acceptedobject

Delete of more than 100 contacts queued to run in the background

Response fields application/json
actionstringdeleterequired
statusstringqueuedrequired
contact_countintegerrequired
messagestringrequired
422Unprocessable Entity

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

GET
https://api.nitrosend.com/v1/my/contacts/{id}

Parameters

idintegerrequiredpath

Response

200OKContact

Contact with channels

Response fields application/json
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a contact

DELETE
https://api.nitrosend.com/v1/my/contacts/{id}

Parameters

idintegerrequiredpath

Response

200OKContact

Deleted contact

Response fields application/json
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>

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

PATCH
https://api.nitrosend.com/v1/my/contacts/{id}

Body

application/json
first_namestring
last_namestring
emailstring<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).

phonestring

E.164 format. Several contacts in a brand may share a phone, so a phone another contact holds is accepted.

sourcestring
country_codestring
opt_inboolean | null

Consent 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>
dataobject

Custom 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".

Example
{
  "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.

Show child attributes
idinteger
kindstringemailphone
valuestring
subscribedboolean

Explicit consent change for this channel. Omission preserves state. A replacement phone number requires a fresh opt-in; suppression cannot be removed by opting in.

_destroyboolean

Parameters

idintegerrequiredpath

Response

200OKContact

Updated contact

Response fields application/json
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/contacts/enrichment/quote

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

application/json

Exactly one same-Brand selection. Existing identity and profile ownership are preserved.

One of
contact_idsArray<integer>
any

Response

Exact maximum-charge quote and work classification

Response fields application/json
quote_digeststring
selected_countintegerrequired
already_current_countintegerrequired
reusable_countintegerrequired
provider_required_countintegerrequired
unavailable_countintegerrequired
maximum_billable_outcomesintegerrequired
resourcestringcontact_profile_enrichment
unit_rate_centsstringrequired
maximum_charge_centsintegerrequired
currencystringUSDrequired
price_book_versionstringrequired
availablebooleanrequired
reasonstring | null
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/contacts/enrichment

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

application/json

Exactly one same-Brand selection. Existing identity and profile ownership are preserved.

One of
contact_idsArray<integer>
any

Parameters

Idempotency-Keystringrequiredheader

Response

Exact idempotent replay

Response fields application/json
selected_countintegerrequired
queued_countintegerrequired
already_current_countintegerrequired
reusable_countintegerrequired
provider_required_countintegerrequired
unavailable_countintegerrequired
maximum_charge_centsintegerrequired
currencystringUSDrequired
price_book_versionstringrequired
idempotent_replaybooleanrequired

Enrichment queued

Response fields application/json
selected_countintegerrequired
queued_countintegerrequired
already_current_countintegerrequired
reusable_countintegerrequired
provider_required_countintegerrequired
unavailable_countintegerrequired
maximum_charge_centsintegerrequired
currencystringUSDrequired
price_book_versionstringrequired
idempotent_replaybooleanrequired
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Account funding changed before the enrichment hold was created

Response fields application/json
codestringrequired
messagestringrequired
errorbooleanrequired
error_codestringrequired
currencystringrequired
required_centsinteger>= 0required
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired
recovery_actionobjectrequired
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
409ConflictError

Idempotency-Key reused with different Contact IDs

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/contacts/{id}/timeline

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

idintegerrequiredpath
cursorstringquery

Opaque keyset cursor from a prior next_cursor.

limitinteger<= 10025query

Response

200OKobject

A page of timeline entries, newest first

Response headers
X-Next-Cursorstringheader

Present when more entries remain.

Response fields application/json
Show child attributes

One normalised, whitelisted entry in a contact's unified timeline.

idstringrequired

Stable composite id, e.g. "event-123".

kindstringeventactivitylifecyclemessagerequired
typestringrequired

Event/activity/lifecycle type, e.g. checkout, opened, flow_exit.

titlestringrequired

Human-readable label for the entry.

occurred_atstring<date-time>required
metaobjectrequired

Display-only extras (e.g. amount, resource_name). Flow exits include the flow name in resource_name and its exit_event. No internal fields.

next_cursorstring | null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Enrichment facts for a contact

GET
https://api.nitrosend.com/v1/my/contacts/{id}/enrichment

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

idintegerrequiredpath

Response

200OKobject

The contact's resolved enrichment rows

Response fields application/json
rowsArray<object>
Show child attributes
keystring
valueany
groupstringprofessionalcompanylocationcontact_intelligenceother
display_valuestring

Human-readable value using the field catalog's shared presentation contract.

value_typestring
confidencenumber | null
staleboolean
synced_atstring<date-time> | null
integration_labelstring | null

Present only for facts from a connected integration.

field_countinteger
summaryobject
Show child attributes
field_countinteger
stale_countinteger
latest_synced_atstring<date-time> | null
groupsobject
Show child attributes
[key: string]integer
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

List the field catalog for this account

GET
https://api.nitrosend.com/v1/my/contacts/fields

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

Response fields application/json
Show child attributes
idintegerrequired
keystringrequired

Dot-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).

categorystringcontactcustomenrichmentengagementtagrequired

Derived from the key namespace.

  • contact — typed column on the contacts table
  • tag — data.tags array
  • enrichment — reserved enrichment namespaces such as data.apollo.*, data.pdl.*, data.attio.*, data.hubspot.*, data.stripe.*, data.shopify.*, and derived data.nitro.*
  • custom — any other data.* key
  • engagement — future engagement traits (reserved)
field_typestringstringnumberbooleandateenumrequired

Inferred from the first observed value; pinned and never flipped.

presentation_typestringtextnumbercurrencypercentdatedatetimebooleanenumrequired

Shared presentation contract used by fact displays and generated merge tags.

presentation_optionsobjectrequired

Provider-supplied formatting metadata such as decimal precision, currency-code field path, unit scale, or percentage multiplier.

labelstringrequired

Human-readable label. Defaults to a humanised version of the key.

display_labelstring

Source-qualified field label suitable for display.

source_keystring | null
source_namestring | null
object_labelstring | null
source_field_labelstring | null
merge_tagstring | null

Ready-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.

promotedbooleanrequired

Whether this field is pinned as a default column in the contacts grid.

fill_ratestring | null

Percentage of contacts that have a non-null value for this field. Computed asynchronously; may be null if the refresh job has not run yet.

Example
75.0
fill_rate_refreshed_atstring<date-time> | null

When fill_rate was last computed.

created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update a field catalog row (owner/admin only)

PATCH
https://api.nitrosend.com/v1/my/contacts/fields/{id}

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

application/json
promotedboolean

Pin this field as a default column in the contacts grid.

labelstring

Override the human-readable label for this field.

Parameters

idintegerrequiredpath

Response

Updated field catalog row

Response fields application/json
idintegerrequired
keystringrequired

Dot-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).

categorystringcontactcustomenrichmentengagementtagrequired

Derived from the key namespace.

  • contact — typed column on the contacts table
  • tag — data.tags array
  • enrichment — reserved enrichment namespaces such as data.apollo.*, data.pdl.*, data.attio.*, data.hubspot.*, data.stripe.*, data.shopify.*, and derived data.nitro.*
  • custom — any other data.* key
  • engagement — future engagement traits (reserved)
field_typestringstringnumberbooleandateenumrequired

Inferred from the first observed value; pinned and never flipped.

presentation_typestringtextnumbercurrencypercentdatedatetimebooleanenumrequired

Shared presentation contract used by fact displays and generated merge tags.

presentation_optionsobjectrequired

Provider-supplied formatting metadata such as decimal precision, currency-code field path, unit scale, or percentage multiplier.

labelstringrequired

Human-readable label. Defaults to a humanised version of the key.

display_labelstring

Source-qualified field label suitable for display.

source_keystring | null
source_namestring | null
object_labelstring | null
source_field_labelstring | null
merge_tagstring | null

Ready-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.

promotedbooleanrequired

Whether this field is pinned as a default column in the contacts grid.

fill_ratestring | null

Percentage of contacts that have a non-null value for this field. Computed asynchronously; may be null if the refresh job has not run yet.

Example
75.0
fill_rate_refreshed_atstring<date-time> | null

When fill_rate was last computed.

created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/direct_uploads

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

application/json
purposestringimportimagemedia_asset

Set to import for CSV contact imports, or image/media_asset for image media assets.

blobobjectrequired
Show child attributes
filenamestringrequired
Example
contacts.csv
byte_sizeintegerrequired
Example
1048576
checksumstringrequired

Base64-encoded MD5 checksum for Active Storage direct upload.

content_typestring
Example
text/csv
metadataobject

Response

Direct-upload reservation

Response fields application/json
signed_idstring

Submit this value to endpoints that consume direct uploads.

filenamestring
byte_sizeinteger
content_typestring | null
direct_uploadobject
Show child attributes
urlstring<uri>
headersobject
Show child attributes
[key: string]string
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/imports

Parameters

pageinteger1query
limitinteger<= 10025query

Response

Paginated import jobs

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
resourcestringcontactsleads
parserstringdefault
statusstringpendingprocessingfailedcanceledcompletecontact_us
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
email_rowsobject | null

Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.

Show child attributes
subscribedinteger
unsubscribedinteger
blockedinteger
warning_rowsinteger

Rows 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.

progressobject

Canonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null
stagesArray<object>
Show child attributes
keystring
labelstring
countinteger
statestringdoneactivependingfailed
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
columnsobject | null
optionsobject | null
assigned_list_idsArray<integer>
assigned_listsArray<object>
Show child attributes
idinteger
namestring

How this import stands against the account's standing row limit.

Show child attributes
tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000
flows_not_startedobject | null

Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.

Show child attributes
flowsArray<object>required
Show child attributes
idinteger
namestring
messagestringrequired
next_stepstringrequired
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/imports

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

application/json
signed_idstringrequired

Active Storage blob signed ID returned by /v1/direct_uploads.

resourcestringcontactsleadscontacts
parserstringdefaultdefault
dry_runbooleanfalse
columnsobject | string | null

CSV 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.

Show child attributes
One of
[key: string]string | null
string
null
Example
{
  "email": "Email",
  "first_name": "First Name",
  "email_status": "Subscribed",
  "email_opt_out": "Unsubscribed",
  "opt_in_at": "Opt In Date"
}
optionsobject | string

Import options as a JSON object or JSON string.

Show child attributes
One of
email_actionstringunsubscribeblock

Optional whole-file action for email in this brand. Omit to preserve subscription choices; recognizable file unsubscribes are always honored.

list_idsArray<integer>
start_flowsbooleanfalse

Start live flows for the contacts this import creates (New contact) and its new list members (Add to list), including existing contacts it adds to a list. Contacts that already existed never enter New contact flows, and contacts already on a list never re-enter its Add to list flows. Only true or false; lead imports and imports with email_action reject it.

string
Example
{
  "list_ids": [
    88
  ]
}

Response

201CreatedImport

Import queued

Response fields application/json
idinteger
resourcestringcontactsleads
parserstringdefault
statusstringpendingprocessingfailedcanceledcompletecontact_us
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
email_rowsobject | null

Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.

Show child attributes
subscribedinteger
unsubscribedinteger
blockedinteger
warning_rowsinteger

Rows 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.

progressobject

Canonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null
stagesArray<object>
Show child attributes
keystring
labelstring
countinteger
statestringdoneactivependingfailed
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
columnsobject | null
optionsobject | null
assigned_list_idsArray<integer>
assigned_listsArray<object>
Show child attributes
idinteger
namestring

How this import stands against the account's standing row limit.

Show child attributes
tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000
flows_not_startedobject | null

Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.

Show child attributes
flowsArray<object>required
Show child attributes
idinteger
namestring
messagestringrequired
next_stepstringrequired
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/imports/spec

Parameters

resourcestringcontactsleadsquery

Optional resource name. Omit to list all schemas.

Response

200OKImportSpec | object

Import schema metadata

Response fields application/json
One of
resourcestringcontactsleadsrequired
parserstringdefaultrequired
uiobject
required_rulesobject
fieldsArray<object>required

Default 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.

guardrailsImportPolicyrequired

Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.

Show child attributes
standingstringrequired

The account standing the limits derive from.

Example
trusted
max_rowsinteger | nullrequired

Row ceiling for one import. Null means no row ceiling for this standing.

Example
null
max_file_size_bytesintegerrequired
Example
2147483648
max_file_size_mbintegerrequired
Example
2048
max_active_importsintegerrequired
Example
10
create_rate_limit_per_minuteintegerrequired
Example
10
direct_upload_rate_limit_per_minuteintegerrequired
Example
30
write_modesArray<string>realshadowdry_runrequired
[key: string]ImportSpec
Show child attributes
resourcestringcontactsleadsrequired
parserstringdefaultrequired
uiobject
required_rulesobject
fieldsArray<object>required

Default 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.

guardrailsImportPolicyrequired

Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.

Show child attributes
standingstringrequired

The account standing the limits derive from.

Example
trusted
max_rowsinteger | nullrequired

Row ceiling for one import. Null means no row ceiling for this standing.

Example
null
max_file_size_bytesintegerrequired
Example
2147483648
max_file_size_mbintegerrequired
Example
2048
max_active_importsintegerrequired
Example
10
create_rate_limit_per_minuteintegerrequired
Example
10
direct_upload_rate_limit_per_minuteintegerrequired
Example
30
write_modesArray<string>realshadowdry_runrequired
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/imports/{id}

Parameters

idintegerrequiredpath

Response

200OKImport

Import job with status, counts, and row errors

Response fields application/json
idinteger
resourcestringcontactsleads
parserstringdefault
statusstringpendingprocessingfailedcanceledcompletecontact_us
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
email_rowsobject | null

Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.

Show child attributes
subscribedinteger
unsubscribedinteger
blockedinteger
warning_rowsinteger

Rows 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.

progressobject

Canonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null
stagesArray<object>
Show child attributes
keystring
labelstring
countinteger
statestringdoneactivependingfailed
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
columnsobject | null
optionsobject | null
assigned_list_idsArray<integer>
assigned_listsArray<object>
Show child attributes
idinteger
namestring

How this import stands against the account's standing row limit.

Show child attributes
tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000
flows_not_startedobject | null

Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.

Show child attributes
flowsArray<object>required
Show child attributes
idinteger
namestring
messagestringrequired
next_stepstringrequired
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete an import record

DELETE
https://api.nitrosend.com/v1/my/imports/{id}

Parameters

idintegerrequiredpath

Response

200OKImport

Deleted import

Response fields application/json
idinteger
resourcestringcontactsleads
parserstringdefault
statusstringpendingprocessingfailedcanceledcompletecontact_us
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
email_rowsobject | null

Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.

Show child attributes
subscribedinteger
unsubscribedinteger
blockedinteger
warning_rowsinteger

Rows 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.

progressobject

Canonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null
stagesArray<object>
Show child attributes
keystring
labelstring
countinteger
statestringdoneactivependingfailed
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
columnsobject | null
optionsobject | null
assigned_list_idsArray<integer>
assigned_listsArray<object>
Show child attributes
idinteger
namestring

How this import stands against the account's standing row limit.

Show child attributes
tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000
flows_not_startedobject | null

Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.

Show child attributes
flowsArray<object>required
Show child attributes
idinteger
namestring
messagestringrequired
next_stepstringrequired
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Cancel a pending or processing import

POST
https://api.nitrosend.com/v1/my/imports/{id}/cancel

Parameters

idintegerrequiredpath

Response

200OKImport

Canceled import

Response fields application/json
idinteger
resourcestringcontactsleads
parserstringdefault
statusstringpendingprocessingfailedcanceledcompletecontact_us
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
email_rowsobject | null

Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.

Show child attributes
subscribedinteger
unsubscribedinteger
blockedinteger
warning_rowsinteger

Rows 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.

progressobject

Canonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null
stagesArray<object>
Show child attributes
keystring
labelstring
countinteger
statestringdoneactivependingfailed
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
columnsobject | null
optionsobject | null
assigned_list_idsArray<integer>
assigned_listsArray<object>
Show child attributes
idinteger
namestring

How this import stands against the account's standing row limit.

Show child attributes
tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000
flows_not_startedobject | null

Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.

Show child attributes
flowsArray<object>required
Show child attributes
idinteger
namestring
messagestringrequired
next_stepstringrequired
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/exports

Parameters

pageinteger1query
limitinteger<= 10025query

Response

Paginated export jobs

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
resourcestringcontactsleads
formatstringcsv
statusstringpendingprocessingcompletefailed
total_rowsinteger | null
rows_writteninteger

Rows written so far; the live numerator against total_rows.

error_messagestring | null
readyboolean

True once the export is complete and the file is available.

download_pathstring | null

Path to download the CSV; present only when ready is true.

progressobject

Live 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.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null

Completion percentage, or null when indeterminate.

stagesArray<object>
Show child attributes
keystring
labelstring
countinteger | null
statestringdoneactivependingfailed
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/exports

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

application/json
resourcestringcontactsleadscontacts
searchstring

Free-text filter, matching the contacts list search.

list_idinteger

Restrict the export to contacts in this list.

tagstring

Restrict the export to contacts with this tag.

Response

201CreatedExport

Export queued

Response fields application/json
idinteger
resourcestringcontactsleads
formatstringcsv
statusstringpendingprocessingcompletefailed
total_rowsinteger | null
rows_writteninteger

Rows written so far; the live numerator against total_rows.

error_messagestring | null
readyboolean

True once the export is complete and the file is available.

download_pathstring | null

Path to download the CSV; present only when ready is true.

progressobject

Live 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.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null

Completion percentage, or null when indeterminate.

stagesArray<object>
Show child attributes
keystring
labelstring
countinteger | null
statestringdoneactivependingfailed
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/exports/{id}

Parameters

idintegerrequiredpath

Response

200OKExport

Export job

Response fields application/json
idinteger
resourcestringcontactsleads
formatstringcsv
statusstringpendingprocessingcompletefailed
total_rowsinteger | null
rows_writteninteger

Rows written so far; the live numerator against total_rows.

error_messagestring | null
readyboolean

True once the export is complete and the file is available.

download_pathstring | null

Path to download the CSV; present only when ready is true.

progressobject

Live 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.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null

Completion percentage, or null when indeterminate.

stagesArray<object>
Show child attributes
keystring
labelstring
countinteger | null
statestringdoneactivependingfailed
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Download a completed export file

GET
https://api.nitrosend.com/v1/my/exports/{id}/download

Returns the CSV file once the export status is complete.

Parameters

idintegerrequiredpath

Response

200OKstring<binary>

CSV file

Response fields text/csv
string<binary>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

Export is not ready

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Lists

Contact lists

List contact lists (paginated)

GET
https://api.nitrosend.com/v1/my/lists

Parameters

namestringquery

Exact case-insensitive list name filter

pageinteger1query
limitinteger<= 10025query

Response

Paginated contact lists

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/lists

Body

application/json
namestringrequired
segment_idinteger | null
contact_idsArray<integer>

Response

201CreatedContactList

List created

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/lists/{id}

Parameters

idintegerrequiredpath

Response

Contact list

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a contact list

DELETE
https://api.nitrosend.com/v1/my/lists/{id}

Parameters

idintegerrequiredpath

Response

Deleted list

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

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

PATCH
https://api.nitrosend.com/v1/my/lists/{id}

Body

application/json
namestring
segment_idinteger | null
contact_idsArray<integer>

Parameters

idintegerrequiredpath

Response

Updated list

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/lists/{id}/delete_warning

Parameters

idintegerrequiredpath

Response

Flows connected to this list

Response fields application/json
campaign_namesArray<string>
flow_namesArray<string>

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

POST
https://api.nitrosend.com/v1/my/lists/{id}/contacts/bulk

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

application/json
actionstringaddremoverequired

Add existing contacts to the list or remove them from it.

emailsArray<string>required

Parameters

idintegerrequiredpath

Response

Bulk list membership result

Response fields application/json
actionstringaddremove
list_idinteger
addedinteger

Contacts newly added for add actions

removedinteger

Contacts removed for remove actions

already_in_listArray<string>
not_in_listArray<string>
not_foundArray<string>
invalid_emailsArray<string>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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)

GET
https://api.nitrosend.com/v1/my/segments

Parameters

pageinteger1query
perinteger<= 100100query

Response

Segments

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
brand_idinteger | null
namestring
originstringusersystem

Who 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.

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
cached_countinteger | null

Last asynchronously refreshed contact count for this segment.

count_computed_atstring<date-time> | null

When cached_count was last refreshed.

created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/segments

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

application/json
namestringrequired

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Response

201CreatedSegment

Segment created

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
originstringusersystem

Who 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.

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
cached_countinteger | null

Last asynchronously refreshed contact count for this segment.

count_computed_atstring<date-time> | null

When cached_count was last refreshed.

created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/segments/{id}

Parameters

idintegerrequiredpath

Response

200OKSegment

Segment

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
originstringusersystem

Who 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.

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
cached_countinteger | null

Last asynchronously refreshed contact count for this segment.

count_computed_atstring<date-time> | null

When cached_count was last refreshed.

created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a segment

DELETE
https://api.nitrosend.com/v1/my/segments/{id}

Parameters

idintegerrequiredpath

Response

200OKSegment

Deleted segment

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
originstringusersystem

Who 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.

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
cached_countinteger | null

Last asynchronously refreshed contact count for this segment.

count_computed_atstring<date-time> | null

When cached_count was last refreshed.

created_atstring<date-time>
updated_atstring<date-time>

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

PATCH
https://api.nitrosend.com/v1/my/segments/{id}

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

application/json
namestring

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Parameters

idintegerrequiredpath

Response

200OKSegment

Updated segment

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
namestring
originstringusersystem

Who 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.

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
cached_countinteger | null

Last asynchronously refreshed contact count for this segment.

count_computed_atstring<date-time> | null

When cached_count was last refreshed.

created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/segments/count

Preview how many contacts match a set of segment filters without creating or saving a segment.

Body

application/json

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Response

200OKobject

Contact count

Response fields application/json
countinteger
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/segments/preview

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

application/json

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Response

Segment preview

Response fields application/json
countinteger

Live count of contacts matching the supplied filters.

sampleArray<object>

Bounded contact sample for quick verification.

Show child attributes
idinteger
emailstring | null
namestring | null
overlapArray<object>

Bounded overlap with existing segments.

Show child attributes
segment_idinteger
namestring
overlap_countinteger
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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)

GET
https://api.nitrosend.com/v1/my/campaigns

Parameters

pageinteger1query
limitinteger<= 10025query

Response

Paginated campaigns

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null

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

POST
https://api.nitrosend.com/v1/my/campaigns

Body

application/json
namestringrequired
channelstringemailsmsemail

Response

201CreatedCampaign

Campaign created

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/campaigns/{id}

Parameters

idintegerrequiredpath

Response

Campaign with trigger, template, and templates

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a campaign

DELETE
https://api.nitrosend.com/v1/my/campaigns/{id}

Parameters

idintegerrequiredpath

Response

Deleted campaign

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null

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

PATCH
https://api.nitrosend.com/v1/my/campaigns/{id}

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

application/json
namestring
statusstring
channelstringemailsms
scheduled_atstring<date-time> | null
trigger_attributesobject
Show child attributes
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target. Use all_contacts only for deliberate all-subscribed-contact sends.

contact_list_idinteger | nulldeprecated
contact_list_idsArray<integer>
segment_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded; pass [] to clear

exclude_contact_list_idsArray<integer>

Contact list IDs whose members are excluded; pass [] to clear

dataobject
template_attributesobject
Show child attributes
if_versionintegerrequired

Required optimistic concurrency token for template content writes. Use the current template.version. A stale value returns 409 with current_version and expected_version.

subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring
from_namestring
from_emailstring<email>
reply_tostring<email>
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring

Parameters

idintegerrequiredpath

Response

Updated campaign

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
402Payment RequiredError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

codeinteger
error_codestringplan_requiredrequired
how_to_fixstringrequired
plan_urlstring<uri>required
409ConflictError

Template version conflict

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/campaigns/{id}/duplicate

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

application/json
cancel_sourcebooleanfalse

When true, cancels the source campaign in the same DB transaction as the duplicate creation.

Parameters

idintegerrequiredpath

Response

201CreatedCampaign

New draft campaign

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Render a campaign email to HTML

GET
https://api.nitrosend.com/v1/my/campaigns/{id}/render

Renders the campaign's current template through the shared preview renderer.

Parameters

idintegerrequiredpath

Response

200OKobject

Rendered HTML

Response fields application/json
htmlstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/campaigns/{id}/readiness

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

idintegerrequiredpath

Response

200OKobject

Structural readiness with optional capacity guidance

Response fields application/json
readybooleanrequired
authoritystringrequired
notestringrequired
checksArray<object>required
Show child attributes
namestringrequired
passedbooleanrequired
messagestringrequired
audience_countinteger | null>= 0
from_emailstring

Exact From address resolved by the canonical sender resolver.

recovery_actionsArray<object>
Show child attributes
typestring
labelstring
urlstring
agent_promptstring

For held or blocked flow emails, each one's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
blocking_issuesArray<string>required
capacity_recoveryDeliveryCapacityRecovery | null
Show child attributes
One of

Informational 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_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
null

Read-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.

Show child attributes
statusstringavailableexhaustednot_applicableunavailablerequired
assessment_scopestringrequired
channelstringrequired
observed_atstring<date-time>required
messagestringrequired
notestringrequired
reason_codestring
retry_atstring<date-time>

UTC release of the blocking calendar allowance; present when exhausted.

remainingobject
Show child attributes
hourinteger>= 0required
dayinteger>= 0required
resets_atobject
Show child attributes
hourstring<date-time>required
daystring<date-time>required

Subject line versions for this campaign's audience. Read only.

Show child attributes
eligibleboolean
audience_countinteger | null
max_versionsinteger
test_sharesobject | null

By number of lines kept (2 up to max_versions): the smallest and the starting winner test share in basis points, and whether sending the winner fits. Null while the audience count is unknown.

Show child attributes
[key: string]object
Show child attributes
min_bpinteger
default_bpinteger
winner_availableboolean
wait_hoursArray<integer>
statusstringnonewritingreadyunavailable
phasestringchecking

While writing: the lines are written and their checks have begun. Absent before that.

reasonstring
linesArray<object>

Suggested alternatives for the current content.

Show child attributes
subjectstring
approachstring
generation_event_idinteger
candidate_locatorstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

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.

Response headers
Retry-Afterintegerheader

Seconds to wait before retrying.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Ask for suggested alternatives to the subject line

POST
https://api.nitrosend.com/v1/my/campaigns/{id}/subject_versions

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

idintegerrequiredpath

Response

200OKobject

The request's state for the current content

Response fields application/json
statusstringnonewritingreadyunavailablerequired
reasonstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get current campaign delivery progress

GET
https://api.nitrosend.com/v1/my/campaigns/{id}/delivery

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

idintegerrequiredpath

Response

Current campaign delivery progress

Response fields application/json

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
stop_reasonstring | null

Why a stopped send stopped, such as email_under_review for one held by the safety check.

safety_reviewobject | null

For 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.

Show child attributes
how_to_fixstring
categorystring
agent_promptstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject

For a send it couldn't read, the images and other changes (as SendRefusalDetail details).

campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
terminalbooleanrequired

True when clients can stop polling.

poll_after_secondsinteger | nullrequired

Suggested polling delay for active sends.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Send a test email for a campaign

POST
https://api.nitrosend.com/v1/my/campaigns/{id}/send_test

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

application/json
emailstring<email>
emailsArray<string>
send_test_toArray<string>
contact_idinteger
sample_contact_idinteger

Contact whose projected data personalizes the test without changing the test recipient.

event_dataobject

Sample data for event fields in this test (max 32KB); never records an Event or Order. Campaign products remain fixed, not event-bound.

Parameters

idintegerrequiredpath
Idempotency-Keystringrequiredheader

Response

Test email sent

Response fields application/json
outcomestringsentpartialpendingheldfaileddry_rundelivered

Dispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.

sentintegerrequired

Number of tests accepted by the sending provider.

pendinginteger
heldinteger

Tests awaiting content review; not sent and not automatically replayed after approval.

failedinteger
dry_runboolean
resultsArray<object>required
Show child attributes
emailstring
successboolean

The sending provider accepted this test; recipient delivery is separate.

statusstringsentdeliveredpendingheldfailed

held awaits content review and was not sent; delivered is the legacy acceptance label.

codestring
messagestring

Human-readable dispatch or provider-feedback detail.

errorstring

Why this recipient's test was not sent.

hold_idinteger

Exact content review case for this test.

plan_urlstring<uri>

Where to choose a plan. Present when code is test_send_cap_reached: a Setup mode account has used its 20 test recipients for the rolling 24 hours.

how_to_fixstring

Explicit recovery guidance; approval alone does not send a test.

agent_promptstring

The reason and fix to paste to an agent

Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject

For a test the safety check couldn't read, each image that failed and the other changes to make.

Show child attributes
imagesArray<object>
changesArray<object>
message_idinteger
provider_idstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/campaigns/{id}/send

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

application/json
expected_campaign_updated_atstring<date-time>required

Exact campaign.updated_at value from the persisted draft being approved for delivery.

template_if_versionintegerrequired

Exact persisted campaign template version being approved for delivery.

deliver_atstring<date-time>

Future delivery time. Omit for immediate delivery.

confirm_send_to_allboolean

Required when the persisted audience is all_contacts.

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.

Show child attributes
subjectstringrequired
generation_event_idinteger

From a suggested line in readiness versions.lines.

candidate_locatorstring

From a suggested line in readiness versions.lines.

Send 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.

Show child attributes
test_share_percentinteger[1, 95]required

From readiness versions.test_shares[n].min_bp / 100 up to 95.

wait_hoursinteger248244
measurestringopensclicksopens

Parameters

idintegerrequiredpath

Response

Campaign sent

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
402Payment RequiredError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

codeinteger
error_codestringplan_requiredrequired
how_to_fixstringrequired
plan_urlstring<uri>required
409ConflictError

Template version conflict or duplicate send attempt

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/workspace/attention

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]1query
throughbooleanfalsequery

Return the prefix through this page to refresh an expanded queue in one read.

Response

200OKobject

Current actions and next-page pointer (not a total count)

Response fields application/json
Show child attributes
keystringrequired
titlestringrequired
detailstringrequired
statestringaction_requiredworkingrequired
blockingbooleanrequired
updated_atstring<date-time>required
toWorkspaceRoute | nullrequired
Show child attributes
One of
namestringrequired
paramsobject
queryobject
null
actionstringrequired
hrefstring
progressobject
dismissibleboolean
chat_session_idinteger
priorityinteger

Account-wide restrictions use 0 and precede individual tasks.

recovery_actionsArray<object>

Existing recovery actions for this restriction; opening one never approves or resumes sending.

Show child attributes
typestringrequired
labelstringrequired
urlstringrequired
next_pageinteger | nullrequired
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Read agent and API control-plane activity for the current brand

GET
https://api.nitrosend.com/v1/my/workspace/activity

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

sourcestringmcpnitrollmapiquery
outcomestringokerrorunknownquery
beforeinteger>= 1query

Read older entries using the previous response's next_cursor.

Response

200OKobject

Recorded activity and continuation cursor

Response fields application/json
Show child attributes
idintegerrequired
sourcestringmcpnitrollmapirequired
titlestringrequired
outcomestringokincompleteacceptedstreameddeniederrorhttp_errorunknownrequired
clientstring | nullrequired
created_atstring<date-time>required
toWorkspaceRoute | nullrequired
Show child attributes
One of
namestringrequired
paramsobject
queryobject
null
next_cursorinteger | nullrequired
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Search the current brand beyond locally loaded pages

GET
https://api.nitrosend.com/v1/my/workspace/search

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

qstringquery

Response

200OKobject

Bounded matches with application navigation targets

Response fields application/json
itemsArray<object>required
Show child attributes
idstringrequired
labelstringrequired
groupstringrequired
typestringcampaignflowlistcontactrequired
toWorkspaceRouterequired
Show child attributes
namestringrequired
paramsobject
queryobject
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service Unavailable

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

GET
https://api.nitrosend.com/v1/my/messages

Returns all messages by default. Use source_type to narrow to campaign, flow, transactional, or test sends.

Parameters

source_typestringallcampaignflowtransactionaltestquery

Filter by source. Omit or use 'all' for everything.

flow_idintegerquery

Filter to messages from a specific flow

campaign_idintegerquery

Filter to messages from a specific campaign

datestring<date>query

Filter to messages created on this date

channelstringemailsmsquery
statusstringqueuedsentfailedquery
pageinteger1query
limitinteger<= 10025query

Response

Paginated list of messages

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
channelstringemailsms
tostring
recipientsobject

Full normalized email envelope, visible only to authorized account readers. Returned for email messages.

Show child attributes
toArray<string>
ccArray<string>
bccArray<string>
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
rfc_message_idstring | null

Actual 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 | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflowtest

campaign, flow, test, or null (transactional)

source_namestring | null

Name of source campaign or flow

status_reason_codestring | null

Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

status_reasonstring | null

Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdelivery

Broad category for status_reason.

failure_codestring | null

Stable machine-readable failure reason; present only when status is failed.

failure_reasonstring | null

Human-readable failure explanation; present only when status is failed.

failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdelivery

Broad category for failure_reason; present only when status is failed.

sent_atstring<date-time> | null
created_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/messages

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

application/json
channelstringemailsmsrequired
tostringrequired

Recipient 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.

subjectstring

Email subject line (required for email channel)

bodystring

Message 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.

htmlstring

Pre-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_idinteger

Load email design from an existing template (email only)

contact_idinteger

Optional contact to personalize with when rendering a template

fromstring

Verified sender email for this email message. May include a display name, for example "Acme hello@example.com".

from_emailstring

Verified sender email for this email message. Alias of from.

from_namestring

Sender display name for this email message

reply_tostring

Reply-to email address for this email message

headersobject

Provider headers for this email message. Structural and Nitrosend-reserved headers are rejected.

Show child attributes
[key: string]string
tagsobject

Provider 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.

Show child attributes
[key: string]string
dataobject

Merge variables

A 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.

Show child attributes
@contextstringhttps://mailschema.org/contexts/map-0.3.jsonldrequired
@typestringMailActionrequired
@idstring<uri>required

Identifies the interaction.

profilestringhttps://mailschema.org/profiles/map/0.3required
typeobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired
contractDigeststringrequired
issuedAtstring<date-time>required
expiresAtstring<date-time>required
inLanguagestringrequired
serviceobjectrequired
Show child attributes
idstring<uri>required

The service's HTTPS origin.

tenantstring<uri>
recipientstring<email>required
subjectobjectrequired
Show child attributes
idstring<uri>required
titlestringrequired
termsobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired

Opaque; a decision names it exactly.

detailsobjectrequired

Defined by the type contract's details schema.

operationsArray<object>required
Show child attributes
idstringrequired
capabilityobject
humanobjectrequired
Show child attributes
urlstring<uri>required
idempotency_keystring

Stable idempotency key (alternative to the header). One of the two is required.

Parameters

Idempotency-Keystringheader

Required 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

Response fields application/json
idinteger
channelstringemailsms
tostring
recipientsobject

Full normalized email envelope, visible only to authorized account readers. Returned for email messages.

Show child attributes
toArray<string>
ccArray<string>
bccArray<string>
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
rfc_message_idstring | null

Actual 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 | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflowtest

campaign, flow, test, or null (transactional)

source_namestring | null

Name of source campaign or flow

status_reason_codestring | null

Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

status_reasonstring | null

Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdelivery

Broad category for status_reason.

failure_codestring | null

Stable machine-readable failure reason; present only when status is failed.

failure_reasonstring | null

Human-readable failure explanation; present only when status is failed.

failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdelivery

Broad category for failure_reason; present only when status is failed.

sent_atstring<date-time> | null
created_atstring<date-time>
ignored_fieldsArray<string>required

Top-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.

Message created

Response fields application/json
idinteger
channelstringemailsms
tostring
recipientsobject

Full normalized email envelope, visible only to authorized account readers. Returned for email messages.

Show child attributes
toArray<string>
ccArray<string>
bccArray<string>
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
rfc_message_idstring | null

Actual 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 | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflowtest

campaign, flow, test, or null (transactional)

source_namestring | null

Name of source campaign or flow

status_reason_codestring | null

Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

status_reasonstring | null

Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdelivery

Broad category for status_reason.

failure_codestring | null

Stable machine-readable failure reason; present only when status is failed.

failure_reasonstring | null

Human-readable failure explanation; present only when status is failed.

failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdelivery

Broad category for failure_reason; present only when status is failed.

sent_atstring<date-time> | null
created_atstring<date-time>
ignored_fieldsArray<string>required

Top-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.

400Bad RequestError

Missing idempotency key (idempotency_key_required).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

402Payment RequiredError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

codeinteger
error_codestringplan_requiredrequired
how_to_fixstringrequired
plan_urlstring<uri>required
409Conflictobject

Idempotency conflict or explicit sender selection required; no new message is retained in either case

Response fields application/json
One of
codeinteger
Example
409
messagestring
errorboolean
Example
true
error_codestringidempotency_conflict
codestringsender_identity_selection_requiredrequired
messagestringrequired
errorbooleanrequired
error_codestringsender_identity_selection_requiredrequired
retryablebooleanrequired
brand_subdomainBrandSubdomainrequired
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

422Unprocessable EntityError & object & SendRefusalDetail

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
ignored_fieldsArray<string>

Present 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_denied
how_to_fixstring

The 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.

categorystring

The 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_promptstring

The reason and fix as one paragraph to paste to an agent. Names IDs only, never text from the email.

Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject
Show child attributes
imagesArray<object>

Each image that couldn't be loaded.

Show child attributes
urlstring

The image address

problemstringnot_foundrefusedrejectedserver_errorunreachableprivate_hostunsupported_typetoo_largetoo_many_pixelsunreadablenot_a_web_addressunsupported_inline_image
http_statusinteger

The image host's HTTP status

changesArray<object>

Other changes the email needs before it can be checked.

Show child attributes
codestring
fixstring
review_idinteger

The held or blocked case, for a request to the team.

model_reasonstring

The safety check's own reason, for trusted accounts only.

503Service UnavailableError & object | object

Admission evidence or the shared hosted-sender root is temporarily unavailable

Response fields application/json
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

error_codestringdelivery_evidence_pendingrequired
retryablebooleanrequired
retry_atstring<date-time>required
codestringhosted_sender_root_unavailablerequired
messagestringrequired
errorbooleanrequired
error_codestringhosted_sender_root_unavailablerequired
retryablebooleanrequired
brand_subdomainBrandSubdomainrequired
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

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)

GET
https://api.nitrosend.com/v1/my/messages/sends

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_typestringcampaignflowtransactionaltestquery

Restrict to one source. Omit for every source.

sincestringtoday7d30d3mquery

Window by send time (creation time while unsent). Omit for all time.

failedbooleanquery

Only failed messages. Their rows report no engagement.

campaign_idintegerquery

Only messages of this campaign's flows.

limitinteger[1, 100]50query

Maximum rows (1-100, default 50). Counts and engagement are not limited.

Response

Sending log rows, filter counts and the Activity engagement.

Response fields application/json
Show child attributes
source_typestringcampaignflowtransactionaltestrequired
row_keystringrequired
source_idinteger | null

Campaign or flow id; null for transactional and test rows.

source_namestringrequired
datestring<date> | null

Creation day of a transactional or test row.

subjectstring | null
recipientsstring | null
recipients_countinteger
totalintegerrequired

Messages in the row (every status and channel) within the window.

sentintegerrequired

Messages of the row the provider accepted (every channel).

failedintegerrequired
queuedintegerrequired
latest_failure_codestring | null
latest_failure_reasonstring | null
latest_failure_categorystring | null
last_sent_atstring<date-time> | null
deliveredintegerrequired

The row's provider-confirmed deliveries (0 on test and failed-only rows).

non_bouncedinteger

Accepted non-test emails minus known bounces.

unconfirmedinteger

Accepted non-test emails without a final provider outcome.

openedintegerrequired

Non-bounced emails of the row opened at least once; privacy image loads can count.

clickedintegerrequired

Non-bounced emails of the row clicked at least once.

open_ratenumberrequired

Percentage (0-100, 1 dp) of non_bounced; 0 without a denominator.

click_ratenumberrequired

Percentage (0-100, 1 dp) of non_bounced; 0 without a denominator.

deliveryobject

Send progress of a campaign row with an active send (same projection as the campaign delivery endpoints).

countsMessageSendsCountsrequired

Message counts for the filter pills, over the same window as the rows.

Show child attributes
allintegerrequired

Messages of every source in the since window (with failed).

campaignintegerrequired
flowintegerrequired
transactionalintegerrequired
testintegerrequired
timeobjectrequired

Messages of the selected source (with failed) per window.

Show child attributes
allintegerrequired
todayintegerrequired
7dintegerrequired
30dintegerrequired
3mintegerrequired
engagementMessageSendsEngagementrequired
Show child attributes
intervalstringhourdaymonthrequired

Series bucket size (hour for today, month for all time, otherwise day).

summaryEngagementCohortBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

seriesArray<object & EngagementCohortBucket>required

One entry per interval of the window (zero-filled), plus any later interval with sends; entries add up to summary.

Show child attributes
bucket_startstring<date-time>required

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.

sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

has_sendsbooleanrequired

Whether the source has ever accepted a non-test email (outside the window too).

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get a transactional message

GET
https://api.nitrosend.com/v1/my/messages/{id}

Parameters

idintegerrequiredpath

Response

200OKMessage

Message

Response fields application/json
idinteger
channelstringemailsms
tostring
recipientsobject

Full normalized email envelope, visible only to authorized account readers. Returned for email messages.

Show child attributes
toArray<string>
ccArray<string>
bccArray<string>
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
rfc_message_idstring | null

Actual 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 | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflowtest

campaign, flow, test, or null (transactional)

source_namestring | null

Name of source campaign or flow

status_reason_codestring | null

Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

status_reasonstring | null

Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdelivery

Broad category for status_reason.

failure_codestring | null

Stable machine-readable failure reason; present only when status is failed.

failure_reasonstring | null

Human-readable failure explanation; present only when status is failed.

failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdelivery

Broad category for failure_reason; present only when status is failed.

sent_atstring<date-time> | null
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Render a message subject and HTML for preview

GET
https://api.nitrosend.com/v1/my/messages/{id}/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

idintegerrequiredpath

Response

200OKobject

Rendered preview, or a typed empty state.

Response fields application/json
subjectstring | null

Rendered subject as plain text, not HTML-escaped. Null for non-email messages or a blank stored subject. Independent of the body empty state; consumers should display it as text.

htmlstring | null

Rendered HTML, or null when empty is true.

formatstring | nulltemplaterawplain

Composition source of the html, or null when empty.

emptyboolean

True when no HTML could be rendered (see reason).

reasonstring | nullnot_previewabletemplate_no_designtemplate_missingtemplate_render_error

Why the preview is empty, when empty is true.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Suppressions

Account suppression list and deliverability diagnostics

List suppressions

GET
https://api.nitrosend.com/v1/my/suppressions

Returns the authenticated account's current suppression records by default, including bounded provider diagnostics when the source feedback event is available.

Parameters

idintegerquery

Filter to a specific suppression ID

emailstring<email>query

Filter to a specific suppressed email address

reasonstringhard_bouncesoft_bouncecomplaintmanualadminunsubscribeverificationmarketing_withheldunconfirmedquery
source_providerstringquery

Filter by provider that emitted the source event

activebooleantruequery

Defaults to true. Set false to list expired suppressions.

pageinteger1query
limitinteger<= 10025query

Response

Paginated list of suppressions

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes

Account suppression row with bounded source-event diagnostics.

idinteger
emailstring<email>
reasonstringhard_bouncesoft_bouncecomplaintmanualadminunsubscribeverificationmarketing_withheldunconfirmed
scopestringaccount_scopedbrand_scoped
brand_idinteger | null

Brand affected by a brand-specific stop.

activeboolean
contact_idinteger | null
source_providerstring | null
source_event_idstring | null
provider_diagnosticstring | null

Bounded diagnostic text extracted from the provider feedback event, when retained.

bounce_typestring | nullhardsoft
bounce_subtypestring | null
complaint_feedback_typestring | null
event_occurred_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

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

GET
https://api.nitrosend.com/v1/my/webhooks

The current brand's webhook endpoints, oldest first, each with its newest delivery. Secrets are masked.

Parameters

pageinteger1query
limitinteger<= 10025query

Response

Paginated list of webhooks

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
urlstring<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.disabled
enabledboolean
statusstringactivefailingdisabled

failing while deliveries fail; an endpoint failing for 3 days is turned off.

failing_sincestring<date-time> | null
secretstring

Standard Webhooks signing secret (whsec_...). Masked unless revealed.

last_deliveryobject | null
Show child attributes
idinteger
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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
updated_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Register a webhook endpoint

POST
https://api.nitrosend.com/v1/my/webhooks

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

application/json
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.disabled
enabledboolean
any

Response

201CreatedWebhook

Webhook created, secret revealed

Response fields application/json
idinteger
urlstring<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.disabled
enabledboolean
statusstringactivefailingdisabled

failing while deliveries fail; an endpoint failing for 3 days is turned off.

failing_sincestring<date-time> | null
secretstring

Standard Webhooks signing secret (whsec_...). Masked unless revealed.

last_deliveryobject | null
Show child attributes
idinteger
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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
updated_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/webhooks/{id}

Parameters

idintegerrequiredpath
revealbooleanfalsequery

Return the signing secret in full.

Response

200OKWebhook

Webhook

Response fields application/json
idinteger
urlstring<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.disabled
enabledboolean
statusstringactivefailingdisabled

failing while deliveries fail; an endpoint failing for 3 days is turned off.

failing_sincestring<date-time> | null
secretstring

Standard Webhooks signing secret (whsec_...). Masked unless revealed.

last_deliveryobject | null
Show child attributes
idinteger
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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
updated_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a webhook and its delivery history

DELETE
https://api.nitrosend.com/v1/my/webhooks/{id}

Parameters

idintegerrequiredpath

Response

200OKWebhook

Webhook deleted

Response fields application/json
idinteger
urlstring<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.disabled
enabledboolean
statusstringactivefailingdisabled

failing while deliveries fail; an endpoint failing for 3 days is turned off.

failing_sincestring<date-time> | null
secretstring

Standard Webhooks signing secret (whsec_...). Masked unless revealed.

last_deliveryobject | null
Show child attributes
idinteger
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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
updated_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update a webhook

PATCH
https://api.nitrosend.com/v1/my/webhooks/{id}

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

application/json
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.disabled
enabledboolean

Parameters

idintegerrequiredpath

Response

200OKWebhook

Webhook updated

Response fields application/json
idinteger
urlstring<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.disabled
enabledboolean
statusstringactivefailingdisabled

failing while deliveries fail; an endpoint failing for 3 days is turned off.

failing_sincestring<date-time> | null
secretstring

Standard Webhooks signing secret (whsec_...). Masked unless revealed.

last_deliveryobject | null
Show child attributes
idinteger
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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
updated_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/webhooks/{id}/test

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

application/json
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.disabled

Parameters

idintegerrequiredpath

Response

202AcceptedWebhookDelivery

Test event queued

Response fields application/json
idinteger
event_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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
last_errorstring | null
next_attempt_atstring<date-time>
Show child attributes
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.disabledrequired
timestampstring<date-time>required
dataobjectrequired
Show child attributes
message_idinteger | null

The id POST /v1/my/messages returned. Null on test events.

tostring
subjectstring | null
idempotency_keystring | null

The caller's Idempotency-Key, when one was sent.

tagsobject

The caller's delivery-option tags.

Show child attributes
[key: string]string
testboolean

Present and true on test events.

sent_atstring<date-time>

email.sent

bounceobject

email.bounced

Show child attributes
typestringhardsoft
subtypestring | null

The provider's bounce subtype, e.g. NoEmail or MailboxFull.

complaintobject

email.complained

Show child attributes
feedback_typestring | null

e.g. abuse

urlstring

email.clicked

failureobject

email.failed

Show child attributes
codestring
reasonstring
categorystring
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

Unknown event type, or the webhook is off

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

List a webhook's deliveries

GET
https://api.nitrosend.com/v1/my/webhooks/{id}/deliveries

The last 7 days of deliveries to this webhook, newest first.

Parameters

idintegerrequiredpath
pageinteger1query
limitinteger<= 10025query

Response

Paginated list of deliveries

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
event_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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
last_errorstring | null
next_attempt_atstring<date-time>
Show child attributes
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.disabledrequired
timestampstring<date-time>required
dataobjectrequired
Show child attributes
message_idinteger | null

The id POST /v1/my/messages returned. Null on test events.

tostring
subjectstring | null
idempotency_keystring | null

The caller's Idempotency-Key, when one was sent.

tagsobject

The caller's delivery-option tags.

Show child attributes
[key: string]string
testboolean

Present and true on test events.

sent_atstring<date-time>

email.sent

bounceobject

email.bounced

Show child attributes
typestringhardsoft
subtypestring | null

The provider's bounce subtype, e.g. NoEmail or MailboxFull.

complaintobject

email.complained

Show child attributes
feedback_typestring | null

e.g. abuse

urlstring

email.clicked

failureobject

email.failed

Show child attributes
codestring
reasonstring
categorystring
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Templates

Email templates, preview, and component schema

Ingest an image media asset

POST
https://api.nitrosend.com/v1/my/images

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/jsonobject
image_datastring

Raw 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_idstring

Active Storage blob signed ID returned by /v1/direct_uploads after uploading bytes with purpose image or media_asset.

filenamestring

Original filename for image_data uploads, or optional filename override for image_url/signed_id sources.

content_typestring | null

Optional MIME type hint when image_data is raw base64 rather than a data URL.

multipart/form-dataobject
filestring<binary>

PNG, JPEG, GIF, or WebP file upload. Must be under 10MB.

filenamestring

Optional filename override.

content_typestring | null

Optional MIME type override.

Response

201CreatedImageAsset

Ingested image asset

Response fields application/json
media_kindstringimage
media_urlstring<uri>
image_urlstring<uri>
signed_idstring
filenamestring
content_typestring
byte_sizeinteger
widthinteger | null

Intrinsic pixel width when detectable.

heightinteger | null

Intrinsic pixel height when detectable.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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)

GET
https://api.nitrosend.com/v1/my/templates

Returns a summary view with section counts (not full design).

Parameters

pageinteger1query
perinteger<= 100100query
scopestringallstandaloneallquery

Use standalone for reusable library templates. Omit or use all to retain the complete designed-template result.

include_previewsbooleanquery

When set, each summary includes rendered preview_html (cached per template version)

Response

Template summaries

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
namestring | null
versioninteger
content_formatEmailContentFormatdesignedplain

Durable 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 | null

Rendered preview, present only with ?include_previews=1

subjectstring | null
preheaderstring | null
flow_idinteger | null
section_countinteger
section_typesArray<string>
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/templates

Creates one standalone template. Idempotency-Key is required; an exact retry returns the original template, while reuse with changed input returns 409.

Body

application/json
namestring
subjectstring
bodystring

Author text in plain format; custom text alternative in designed format.

content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
if_versioninteger

Required optimistic concurrency token. Use the current template.version.

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
catalog_idstring

The 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-Keystringrequiredheader

Response

Exact idempotent replay of an existing template

Response fields application/json
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
201CreatedTemplate

Created template

Response fields application/json
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Idempotency-Key reused with changed input

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/templates/{id}

Parameters

idintegerrequiredpath

Response

Full template including design

Response fields application/json
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete an unused standalone template

DELETE
https://api.nitrosend.com/v1/my/templates/{id}

Parameters

idintegerrequiredpath
if_versionintegerrequiredquery

Required optimistic concurrency token. Use the current template.version.

Response

200OKobject

Template deleted

Response fields application/json
deletedbooleanrequired
Example
true
template_idintegerrequired
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Template version conflict or deletion blocked by message/flow history

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update a template

PATCH
https://api.nitrosend.com/v1/my/templates/{id}

Body

application/json
namestring
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring
if_versionintegerrequired

Required optimistic concurrency token. Use the current template.version. A stale value returns 409 with current_version and expected_version.

from_namestring
from_emailstring<email>
reply_tostring<email>
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring

Parameters

idintegerrequiredpath

Response

Updated template

Response fields application/json
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
409ConflictError

Template version conflict

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/templates/{id}/render

Renders the template through the shared preview renderer.

Parameters

idintegerrequiredpath

Response

200OKobject

Rendered HTML

Response fields application/json
htmlstringrequired
accessibilityEmailAccessibilityLintrequired

Advisory accessibility lint result for rendered email previews

Show child attributes
product_bindingsArray<object>
Show child attributes
pathstring
availableinteger
displayedinteger
truncatedboolean
validboolean

Always true while accessibility lint is advisory-only

Show child attributes
levelstring
Example
warning
rulestring
Example
image_alt_text
messagestring
suggested_fixstring
countinteger
min_rationumber<float>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/templates/{id}/send_test

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

application/json
emailstring | Array<string>
Show child attributes
One of
string<email>
Array<string>
emailsArray<string>
send_test_toArray<string>
contact_idinteger
sample_contact_idinteger

Contact whose projected data personalizes the test without changing the test recipient.

Parameters

idintegerrequiredpath
Idempotency-Keystringrequiredheader

Response

Test email sent

Response fields application/json
outcomestringsentpartialpendingheldfaileddry_rundelivered

Dispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.

sentintegerrequired

Number of tests accepted by the sending provider.

pendinginteger
heldinteger

Tests awaiting content review; not sent and not automatically replayed after approval.

failedinteger
dry_runboolean
resultsArray<object>required
Show child attributes
emailstring
successboolean

The sending provider accepted this test; recipient delivery is separate.

statusstringsentdeliveredpendingheldfailed

held awaits content review and was not sent; delivered is the legacy acceptance label.

codestring
messagestring

Human-readable dispatch or provider-feedback detail.

errorstring

Why this recipient's test was not sent.

hold_idinteger

Exact content review case for this test.

plan_urlstring<uri>

Where to choose a plan. Present when code is test_send_cap_reached: a Setup mode account has used its 20 test recipients for the rolling 24 hours.

how_to_fixstring

Explicit recovery guidance; approval alone does not send a test.

agent_promptstring

The reason and fix to paste to an agent

Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject

For a test the safety check couldn't read, each image that failed and the other changes to make.

Show child attributes
imagesArray<object>
changesArray<object>
message_idinteger
provider_idstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/templates/preview

Body

application/json
event_dataobject

Original trigger data used only for this preview (max 32KB).

documentobjectrequired

Source-free preview preserves the designed default; selecting plain is not accepted.

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
content_formatstring

Response

200OKobject

Rendered HTML

Response fields application/json
htmlstringrequired
accessibilityEmailAccessibilityLintrequired

Advisory accessibility lint result for rendered email previews

Show child attributes
product_bindingsArray<object>
Show child attributes
pathstring
availableinteger
displayedinteger
truncatedboolean
validboolean

Always true while accessibility lint is advisory-only

Show child attributes
levelstring
Example
warning
rulestring
Example
image_alt_text
messagestring
suggested_fixstring
countinteger
min_rationumber<float>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get the email component schema

GET
https://api.nitrosend.com/v1/my/templates/spec

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

Response fields application/json

Full schema for email design sections. Each component has type, description, props (with types, required flags, defaults), and tips.

versionintegerrequired
design_guidelinesstringrequired
renderer_versionstringrequired

The @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.

componentsArray<object>required
Show child attributes
typestringrequired
descriptionstringrequired
tipsArray<string>
propsobjectrequired
Show child attributes
[key: string]object
Show child attributes
typestringrequired
requiredboolean
defaultany
descriptionstring
enumArray<string>
itemsobject
Show child attributes
[key: string]object
Show child attributes
typestringrequired
descriptionstringrequired
server_ownedboolean
unset_when_emptyboolean

An empty value is allowed in a draft; delivery leaves the section out.

theme_keystring
style_attributesArray<object>required

Standard per-section style attribute registry.

Show child attributes
keystringrequired
labelstringrequired
typestringcolorspacingenumnumberbooleanrequired
applies_toanyrequired
defaultany
theme_fallbackstring
descriptionstringrequired
mininteger
maxinteger
valuesArray<string>
targetobjectrequired
Show child attributes
elstringsectioncontentshaperequired
attrstring
preview_documentobjectrequired
Show child attributes
parameterstringrequired
descriptionstringrequired
exampleobjectrequired
variablesobjectrequired

Merge variables grouped by source namespace.

Show child attributes
[key: string]Array<object>
Show child attributes
namestringrequired
descriptionstringrequired
filtersArray<object>required
Show child attributes
namestringrequired
syntaxstringrequired
descriptionstringrequired
theme_attributesArray<object>required

Brand Kit theme attribute registry (single source of truth for the editor).

Show child attributes
keystringrequired
labelstringrequired
typestringcolorfontnumberenumspacingstringimagearrayrequired
defaultany
categorystringcolorfontvisual_identityidentityrequired
slotstring
surfacesArray<string>required
mininteger
maxinteger
valuesArray<string>
optionsArray<object>
Show child attributes
valuestring
labelstring
descriptionstring
transform_tableobject
Show child attributes
[key: string]string
columnboolean
storagestring
placeholderstring
value_resolverstring
server_ownedboolean
descriptionstring

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

GET
https://api.nitrosend.com/v1/my/templates/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

Response fields application/json
Show child attributes
idstring
namestring
categorystring
tagsArray<string>
descriptionstring
subjectstring

Suggested subject line

preheaderstring

Suggested preheader

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
preview_htmlstring | null
branded_designEmailDesign

Same layout with palette overrides stripped so brand colors apply

Show child attributes

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
branded_preview_htmlstring | null

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

POST
https://api.nitrosend.com/v1/my/templates/generate

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

application/json
goalstringrequired

What the email should accomplish

Example
Welcome new subscribers and introduce the brand
operationstringgenerateregeneraterefinerequired
edit_scopestringcopydesignboth

Defaults to copy for refine and both otherwise.

user_instructionstring
categorystring

Optional category hint (welcome, newsletter, promotion, etc.)

tonestring

Optional tone override (formal, casual, etc.)

current_draftobjectrequired

Complete unsaved editor state to generate or refine. Supplied format must match the scoped stored/source format; unbound new content defaults to designed.

Show child attributes
One of
subjectstring
preheaderstring
bodystring
content_formatstring
plain_text_modestringderivedcustomrequired
from_namestring
from_emailstring
reply_tostring
designobjectrequired
Show child attributes
versioninteger
themeobject
sectionsArray<object>required
content_formatstringrequired
plain_text_modestringrequired
subjectstring
preheaderstring
bodystringrequired
from_namestring
from_emailstring
reply_tostring
designobject

Dormant designed content, preserved during plain authoring.

namestring
triggerFlowTriggerInputrequired
Show child attributes
stop_on_replybooleanfalse

Stop only the enrollment whose tracked email received a proven human reply. Requires monitored receiving.

reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>

New same-brand/contact events after journey entry stop future steps. Pinned in the approved revision; cannot recall a step already executing.

eventstring

Built-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_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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

dataobject
Show child attributes
typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscriberequired
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject

Every declared category key and other must have an explicit path. A branch node ends its sequence.

Show child attributes
reply_allbooleanfalse
ccArray<string>
bccArray<string>
subjectstring

Email step: subject line

bodystring

SMS body or email plain text

content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring

Email step: preheader

from_namestring
from_emailstring
reply_tostring

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
durationinteger>= 0

Wait step: seconds, positive unless send_at is configured

send_atstring

First 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_zonestring

IANA time zone for send_at. Defaults from the account owner or Etc/UTC and is pinned in the approved runtime.

Split step: condition filters

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Split step: yes branch

Split step: no branch

event_namestring

Emit event step: event to fire

forward_event_databooleanfalse
event_dataobject
transactionalbooleanfalse
authoring_targetobjectrequired
Show child attributes
One of
surfacestringrequired
template_idinteger>= 1
if_versioninteger>= 1

Required when template_id is present.

surfacestringrequired
campaign_idinteger>= 1required
template_idinteger>= 1
if_versioninteger>= 1required
surfacestringrequired
flow_idinteger>= 1required
action_namestringrequired
if_versioninteger>= 1required

Parameters

Idempotency-Keystringrequiredheader

Retry-stable identity for this generation request.

Response

200OKobject

Generated email design

Response fields application/json
designobject

{ version, theme, sections[] } — ready for GrapesJS

subjectstring
preheaderstring
bodystring
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
categorystring

Inferred or provided category

prompt_versionstring
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
knowledge_usedArray<string>
400Bad Requestobject

Invalid authoring request

Response fields application/json
codestringidempotency_key_requiredinvalid_authoring_requestrequired
error_codestringidempotency_key_requiredinvalid_authoring_requestrequired
messagestringrequired
errorbooleanrequired
409Conflictobject

Generation or template version conflict

Response fields application/json
codestringtemplate_version_conflictidempotency_conflictgeneration_in_progressgeneration_replay_invalidrequired
error_codestringtemplate_version_conflictidempotency_conflictgeneration_in_progressgeneration_replay_invalidrequired
messagestringrequired
errorbooleanrequired
422Unprocessable EntityError

Validation error

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

429Too Many RequestsError

Rate limit exceeded

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

Generation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Flows

Automation flows and step schema

Save an edited guest flow after sign-in

POST
https://api.nitrosend.com/v1/my/flow_demo/claim

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

application/json
tokenstringrequired
namestring
send_testsbooleanfalse

Send 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.

graphobjectrequired
Show child attributes
triggerobjectrequired
stepsArray<object>required

Parameters

Idempotency-Keystringrequiredheader

Response

201Createdobject

Claimed draft flow and target Brand

Response fields application/json
flow_idintegerrequired
brand_sidstringrequired
inbox_testsstringqueued

Present when send_tests was true and the test sends were queued.

409Conflict

The same demo was claimed with different input or by another account

422Unprocessable Entity

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)

GET
https://api.nitrosend.com/v1/my/flows

Returns standalone flows only (excludes campaign-attached flows).

Parameters

pageinteger1query
limitinteger<= 10025query

Response

Paginated flows

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/flows

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

application/json
namestringrequired
Show child attributes
stop_on_replybooleanfalse

Stop only the enrollment whose tracked email received a proven human reply. Requires monitored receiving.

reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>

New same-brand/contact events after journey entry stop future steps. Pinned in the approved revision; cannot recall a step already executing.

eventstring

Built-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_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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

dataobject
Show child attributes
typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscriberequired
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject

Every declared category key and other must have an explicit path. A branch node ends its sequence.

Show child attributes
reply_allbooleanfalse
ccArray<string>
bccArray<string>
subjectstring

Email step: subject line

bodystring

SMS body or email plain text

content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring

Email step: preheader

from_namestring
from_emailstring
reply_tostring

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
durationinteger>= 0

Wait step: seconds, positive unless send_at is configured

send_atstring

First 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_zonestring

IANA time zone for send_at. Defaults from the account owner or Etc/UTC and is pinned in the approved runtime.

Split step: condition filters

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Split step: yes branch

Split step: no branch

event_namestring

Emit event step: event to fire

forward_event_databooleanfalse
event_dataobject
transactionalbooleanfalse

Parameters

Idempotency-Keystringrequiredheader

Response

200OKFlow

Exact idempotent replay of an existing flow

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
201CreatedFlow

Flow created

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

Idempotency-Key reused with changed input

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/flows/generate

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

application/json
goalstring
template_idstring

A flow template id, sent instead of goal.

contact_list_idinteger

The brand list a list_add template starts on.

Parameters

Idempotency-Keystringrequiredheader

Response

200OKFlow

Exact idempotent replay of an existing flow

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
201CreatedFlow

Flow written and saved as a draft

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

The first request with this key is still writing, or the key was reused with a changed request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

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

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

Planning or writing failed; retry with the same key

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get a flow

GET
https://api.nitrosend.com/v1/my/flows/{id}

Parameters

idintegerrequiredpath
include_blockersbooleantruequery

Pass false to leave blockers out of unpublished_change, as the flow list does, which skips the publish checks. Defaults to true.

Response

200OKFlow

Flow with full graph

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a flow

DELETE
https://api.nitrosend.com/v1/my/flows/{id}

Parameters

idintegerrequiredpath

Response

200OKFlow

Deleted flow

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

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

PATCH
https://api.nitrosend.com/v1/my/flows/{id}

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

application/json
namestring
statusstringdraftlivepausedarchivedcancelled
approval_statestringapprovedrejected
revision_idinteger | null

Optional 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_existing

Required 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 | null

Exact optimistic concurrency token for authored graph changes.

updated_atstring<date-time>

Optimistic concurrency check

Show child attributes
stop_on_replybooleanfalse

Stop only the enrollment whose tracked email received a proven human reply. Requires monitored receiving.

reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>

New same-brand/contact events after journey entry stop future steps. Pinned in the approved revision; cannot recall a step already executing.

eventstring

Built-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_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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

dataobject
Show child attributes
typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscriberequired
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject

Every declared category key and other must have an explicit path. A branch node ends its sequence.

Show child attributes
reply_allbooleanfalse
ccArray<string>
bccArray<string>
subjectstring

Email step: subject line

bodystring

SMS body or email plain text

content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring

Email step: preheader

from_namestring
from_emailstring
reply_tostring

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
durationinteger>= 0

Wait step: seconds, positive unless send_at is configured

send_atstring

First 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_zonestring

IANA time zone for send_at. Defaults from the account owner or Etc/UTC and is pinned in the approved runtime.

Split step: condition filters

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Split step: yes branch

Split step: no branch

event_namestring

Emit event step: event to fire

forward_event_databooleanfalse
event_dataobject
transactionalbooleanfalse
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
publishbooleanfalse

With an authoring save to a live or paused flow, publish the saved revision. Ignored without authoring fields.

Parameters

idintegerrequiredpath

Response

200OKFlow

Updated flow

Response fields application/json
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
402Payment RequiredError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

codeinteger
error_codestringplan_requiredrequired
how_to_fixstringrequired
plan_urlstring<uri>required
409ConflictError

Conflict — the authored draft or requested publication revision is stale

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

For held or blocked flow emails, each one's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring

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

GET
https://api.nitrosend.com/v1/my/flows/{id}/resume_plan

Parameters

idintegerrequiredpath

Response

Current restart impact and available choices

Response fields application/json
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get the flow step type schema

GET
https://api.nitrosend.com/v1/my/flows/spec

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

Response fields application/json

Schema 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.

filtersfilters
Show child attributes
[key: string]object
Show child attributes
titlestring
groupstring
aliasstring

Internal field binding.

summarystring
typestringstringnumberbooleandateenumlistevent
predicatesArray<string>
enum_valuesArray<string>
event_name_sourcestring
recency_optionsArray<string>
sort_keystring

Optional contacts index sort key backed by this filter.

sort_columnstring

Internal SQL column used for server-side sorting.

triggersArray<object>
Show child attributes
titlestring
eventstring
descriptionstring

What fires the trigger.

variablesobject
Show child attributes
pathsArray<object>
Show child attributes
pathstring

Declared event payload path.

typestringstringintegernumberbooleanobjectarray
filtersfilters
Show child attributes
[key: string]object
Show child attributes
titlestring
groupstring
aliasstring

Internal field binding.

summarystring
typestringstringnumberbooleandateenumlistevent
predicatesArray<string>
enum_valuesArray<string>
event_name_sourcestring
recency_optionsArray<string>
sort_keystring

Optional contacts index sort key backed by this filter.

sort_columnstring

Internal SQL column used for server-side sorting.

filter_limitsobject

Limits every filter tree is held to on save. A tree past either limit is refused with invalid_filter.

Show child attributes
max_depthinteger

The deepest level a node may sit at. An explicit root group ({ op, conditions }) is level 0 and its conditions level 1; each nested group or NOT adds one level. A legacy bare-array root puts its items at level 0.

max_conditions_per_groupinteger

The most conditions one group may hold.

stepsArray<object>
Show child attributes
typestring
titlestring
summarystring
paramsobject
Show child attributes
[key: string]object
Show child attributes
labelstring
typestring
requiredboolean
defaultany
descriptionstring

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

GET
https://api.nitrosend.com/v1/my/flow_templates

Returns the gallery templates available to the current account's enabled capabilities. Filter the available templates with category.

Parameters

categorystringquery

Return only this category's available templates, such as ecommerce.

Response

List of flow templates

Response fields application/json
Show child attributes

Lean flow template card for index listings.

idstring

Template slug (e.g. welcome)

type_labelstring
descriptionstring
categorystring
iconstring

Font Awesome icon name for the template's card, without the fa- prefix.

needs_listboolean

Whether creating it takes trigger.contact_list_id, the brand list it starts on.

brand_writableboolean

Whether POST /v1/my/flows/generate can write this template for the brand.

email_countinteger
step_countinteger
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get a flow template

GET
https://api.nitrosend.com/v1/my/flow_templates/{id}

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

idstringrequiredpath

Flow template slug (e.g. welcome)

Response

Flow template with full graph

Response fields application/json

Lean flow template card for index listings.

idstring

Template slug (e.g. welcome)

type_labelstring
descriptionstring
categorystring
iconstring

Font Awesome icon name for the template's card, without the fa- prefix.

needs_listboolean

Whether creating it takes trigger.contact_list_id, the brand list it starts on.

brand_writableboolean

Whether POST /v1/my/flows/generate can write this template for the brand.

email_countinteger
step_countinteger

Full flow template including the graph, ready for POST /v1/my/flows.

triggerobject

Trigger 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.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

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

GET
https://api.nitrosend.com/v1/my/map/approvals/{id}

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

idintegerrequiredpath

Response

The send approval

Response fields application/json
idintegerrequired
campaign_idintegerrequired
can_decidebooleanrequired

Whether the signed-in person may decide it, as the account owner or a direct account admin.

statestringpendingapproveddeclinedexpiredwithdrawnrequired

withdrawn 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_progresscompletedfailedcancelledrequired
contentobjectrequired
Show child attributes
subjectstringrequired
preheaderstring
htmlstringrequired

The exact email the approval sends.

bccstring

The address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.

mail_actionMailActionDescriptionrequired

The Campaign Send Approval 0.1 description of this send's exact terms.

Show child attributes
@contextstringhttps://mailschema.org/contexts/map-0.3.jsonldrequired
@typestringMailActionrequired
@idstring<uri>required

Identifies the interaction.

profilestringhttps://mailschema.org/profiles/map/0.3required
typeobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired
contractDigeststringrequired
issuedAtstring<date-time>required
expiresAtstring<date-time>required
inLanguagestringrequired
serviceobjectrequired
Show child attributes
idstring<uri>required

The service's HTTPS origin.

tenantstring<uri>
recipientstring<email>required
subjectobjectrequired
Show child attributes
idstring<uri>required
titlestringrequired
termsobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired

Opaque; a decision names it exactly.

detailsobjectrequired

Defined by the type contract's details schema.

operationsArray<object>required
Show child attributes
idstringrequired
capabilityobject
humanobjectrequired
Show child attributes
urlstring<uri>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Approve or decline a held campaign send at its terms version

POST
https://api.nitrosend.com/v1/my/map/approvals/{id}

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

application/json
decisionstringapprovedeclinerequired
versionstringrequired

The terms version the decision was made on.

Parameters

idintegerrequiredpath

Response

The send approval after the decision

Response fields application/json
idintegerrequired
campaign_idintegerrequired
can_decidebooleanrequired

Whether the signed-in person may decide it, as the account owner or a direct account admin.

statestringpendingapproveddeclinedexpiredwithdrawnrequired

withdrawn 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_progresscompletedfailedcancelledrequired
contentobjectrequired
Show child attributes
subjectstringrequired
preheaderstring
htmlstringrequired

The exact email the approval sends.

bccstring

The address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.

mail_actionMailActionDescriptionrequired

The Campaign Send Approval 0.1 description of this send's exact terms.

Show child attributes
@contextstringhttps://mailschema.org/contexts/map-0.3.jsonldrequired
@typestringMailActionrequired
@idstring<uri>required

Identifies the interaction.

profilestringhttps://mailschema.org/profiles/map/0.3required
typeobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired
contractDigeststringrequired
issuedAtstring<date-time>required
expiresAtstring<date-time>required
inLanguagestringrequired
serviceobjectrequired
Show child attributes
idstring<uri>required

The service's HTTPS origin.

tenantstring<uri>
recipientstring<email>required
subjectobjectrequired
Show child attributes
idstring<uri>required
titlestringrequired
termsobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired

Opaque; a decision names it exactly.

detailsobjectrequired

Defined by the type contract's details schema.

operationsArray<object>required
Show child attributes
idstringrequired
capabilityobject
humanobjectrequired
Show child attributes
urlstring<uri>required
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

402Payment RequiredError & object

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

codeinteger
error_codestringplan_requiredrequired
how_to_fixstringrequired
plan_urlstring<uri>required
403ForbiddenError

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

The send was already decided, changed since the given version, expired or was withdrawn. Nothing is applied.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Events

Contact event tracking

List events (paginated)

GET
https://api.nitrosend.com/v1/my/events

Parameters

pageinteger1query
limitinteger<= 10050query
eventstringquery

Filter by event type

contact_idintegerquery
created_afterstring<date-time>query
created_beforestring<date-time>query
resource_uidstringquery
resource_namestringquery
testbooleanquery

Response

Paginated events

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/events

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

application/json
eventstringrequired

Event type name (lowercase, underscores)

contact_idinteger
contact_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_keystring

Idempotency key (alternative to header)

amountnumber<double>
resource_uidstring
resource_namestring
resource_urlstring<uri>
testbooleanfalse
dataobject

Custom 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_sourcestring
utm_mediumstring
utm_termstring
utm_contentstring
utm_campaignstring

Parameters

Idempotency-Keystringheader

Idempotency key (alternative to body param)

Response

200OKEvent

Duplicate event (idempotent — returns existing)

Response fields application/json
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>
201CreatedEvent

Event created

Response fields application/json
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409Conflictobject

The correction's order has not arrived. Retry after recording the purchase, using the same idempotency key; no event or phantom order is created.

Response fields application/json
codeinteger
errorboolean
error_codestring
retryableboolean
messagestring
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/events/names

Returns known platform event names plus observed event names for the current brand.

Response

200OKobject

Event name suggestions

Response fields application/json
namesArray<string>

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

GET
https://api.nitrosend.com/v1/my/events/{id}

Parameters

idintegerrequiredpath

Response

200OKEvent

Event

Response fields application/json
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete an event

DELETE
https://api.nitrosend.com/v1/my/events/{id}

Parameters

idintegerrequiredpath

Response

200OKEvent

Deleted event

Response fields application/json
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>

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)

GET
https://api.nitrosend.com/v1/my/domains

Parameters

pageinteger1query
perinteger<= 10030query

Response

Paginated domains

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/domains

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

application/json
domainobjectrequired
Show child attributes
namestringrequired

e.g. send.example.com

Response

201CreatedDomain

Domain registered with DNS records to configure

Response fields application/json
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
503Service UnavailableError

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get a domain with DNS records and status

GET
https://api.nitrosend.com/v1/my/domains/{id}

Parameters

idintegerrequiredpath
inbox_idintegerquery

Select one of this domain's inboxes for receiving setup and forwarding status.

Response

200OKDomain

Domain

Response fields application/json
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Remove a sending domain

DELETE
https://api.nitrosend.com/v1/my/domains/{id}

A paired domain first returns 422 with the exact counterpart impact. Repeat with unpair=true only after the user confirms that outcome.

Parameters

idintegerrequiredpath
unpairbooleanfalsequery

Confirm teardown of an identity pair after reviewing the paired-domain 422 response.

Response

204No Content

Domain deleted

422Unprocessable EntityError & object

Domain is paired or still has dependent inboxes

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

reasonstringdomain_paireddomain_in_use
domain_idinteger
paired_withstring
counterpart_removedboolean
503Service UnavailableError

Upstream service unavailable

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

List shared subdomains and eligible destination brands

GET
https://api.nitrosend.com/v1/my/domains/{domain_id}/subdomains

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_idintegerrequiredpath

Verified apex or paired sending domain owned by the current brand.

pageinteger>= 11query
qstringquery

Filter the destination directory by brand or account name.

Response

Subdomains (25 per page) and up to 100 eligible destinations.

Response fields application/json
parentobjectrequired
Show child attributes
idinteger
namestring
destinationsArray<object>required
Show child attributes
account_idinteger
account_namestring
brand_idinteger
brand_sidstring
brand_namestring
destinations_truncatedbooleanrequired
subdomainsArray<SharedSubdomain>required
Show child attributes
idintegerrequired
namestringrequired

The recipient's visible From domain.

sending_domain_idintegerrequired
sending_domain_namestringrequired
account_idintegerrequired
account_namestringrequired
brand_idintegerrequired
brand_sidstringrequired
brand_namestringrequired
activebooleanrequired

Domain permission is current; DNS verification remains a separate requirement.

revoked_atstring<date-time> | null
dns_verifiedbooleanrequired
paginationobjectrequired
Show child attributes
pageinteger
total_pagesinteger
total_countinteger
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Share an exact subdomain with a brand or managed client

POST
https://api.nitrosend.com/v1/my/domains/{domain_id}/subdomains

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

application/json
subdomainobjectrequired
Show child attributes
subdomainstringrequired

One DNS label below the apex.

brand_sidstringrequired

Exact destination brand in this account or an eligible managed client.

Parameters

domain_idintegerrequiredpath

Verified apex or paired sending domain owned by the current brand.

Response

201CreatedSharedSubdomain

Shared child claim; use the destination brand's domain setup to configure DNS.

Response fields application/json
idintegerrequired
namestringrequired

The recipient's visible From domain.

sending_domain_idintegerrequired
sending_domain_namestringrequired
account_idintegerrequired
account_namestringrequired
brand_idintegerrequired
brand_sidstringrequired
brand_namestringrequired
activebooleanrequired

Domain permission is current; DNS verification remains a separate requirement.

revoked_atstring<date-time> | null
dns_verifiedbooleanrequired
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
429Too Many RequestsError

Too many subdomain creation attempts. Retry later.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

Upstream service unavailable

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Stop sharing a subdomain

DELETE
https://api.nitrosend.com/v1/my/domains/{domain_id}/subdomains/{id}

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_idintegerrequiredpath
idintegerrequiredpath

Response

Child claim with sharing stopped.

Response fields application/json
idintegerrequired
namestringrequired

The recipient's visible From domain.

sending_domain_idintegerrequired
sending_domain_namestringrequired
account_idintegerrequired
account_namestringrequired
brand_idintegerrequired
brand_sidstringrequired
brand_namestringrequired
activebooleanrequired

Domain permission is current; DNS verification remains a separate requirement.

revoked_atstring<date-time> | null
dns_verifiedbooleanrequired
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/domains/{id}/verify

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

idintegerrequiredpath

Response

200OKDomain

The domain, its DNS health and what is outstanding

Response fields application/json
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/domains/{id}/entri_session

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

application/json
apex_mx_overridebooleanfalse

Explicitly include the prepared company-inbox MX cutover in this session.

apex_mx_confirmationstring

Exact apex domain name being approved. Required when apex_mx_override is true.

Parameters

idintegerrequiredpath

Response

Entri bootstrap payload

Response fields application/json
domainDomainrequired
Show child attributes
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
entriobjectrequired
Show child attributes
application_idstringrequired
tokenstringrequired
prefilled_domainstringrequired
user_idstringrequired
dns_recordsArray<EntriDnsRecord>required
Show child attributes
typestring
hoststring
valuestring
ttlinteger
priorityinteger | null
manual_dns_recordsDomainDnsRecordsrequired
Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Domain setup or apex mail cutover is not ready

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether 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.

429Too Many RequestsError

Rate limit exceeded

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

Upstream service unavailable

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Configure inbound delivery for a verified domain

PUT
https://api.nitrosend.com/v1/my/domains/{id}/inbound_setup

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

application/json
inbound_setupobjectrequired
Show child attributes
methodstringprovider_forwardingmxrequired
providerstringgoogle_workspacemicrosoft_365zohoother

Required when method is provider_forwarding.

local_partstring

Select an exact existing address, or request creation subject to the current inbox allowance.

inbox_idinteger

Existing inbox on this domain. Required for an ambiguous setup when local_part is omitted.

display_namestring | null
preparebooleanfalse

Prepare apex receiving before opening the existing Entri MX connection. Does not change DNS.

no_existing_mail_servicebooleanfalse

Explicit first-mailbox choice. Rejected when public MX or a saved route identifies an existing mail service.

Parameters

idintegerrequiredpath

Response

200OKDomain

Updated domain and inbound setup state

Response fields application/json
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/domains/{id}/inbound_setup/probe

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

application/json
inbox_idinteger

An inbox belonging to this domain and brand.

Parameters

idintegerrequiredpath

Response

200OKDomain

Domain with refreshed forwarding probe state

Response fields application/json
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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)

GET
https://api.nitrosend.com/v1/my/integrations

Parameters

categorystringemailsmscrmquery
pageinteger1query
perinteger<= 10030query

Response

Paginated integrations

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Create or connect an email provider integration

POST
https://api.nitrosend.com/v1/my/integrations

Body

application/json
integrationMailgunIntegrationInput | SesIntegrationInput | PostmarkIntegrationInput | ResendIntegrationInput | SendgridIntegrationInput | ActiveCampaignIntegrationInputrequired
Show child attributes
One of
providerstringmailgunrequired
api_keystringrequired
domainstringrequired

Mailgun sending domain

regionstring | null

Optional Mailgun region hint

activebooleantrue
providerstringsesrequired
access_key_idstringrequired
secret_access_keystringrequired
regionstringrequired

AWS SES region

activebooleantrue
providerstringpostmarkrequired
server_tokenstringrequired

Postmark server token for sending email

account_tokenstringrequired

Postmark account token for domains API access

activebooleantrue
providerstringresendrequired
api_keystringrequired
activebooleantrue
providerstringsendgridrequired
api_keystringrequired
activebooleantrue
providerstringactivecampaignrequired
api_urlstring<uri>required

The API URL from ActiveCampaign Settings > Developer, like https://youraccount.api-us1.com. Only https on an ActiveCampaign API host is accepted.

api_keystringrequiredwrite only
activebooleantrue

Response

201CreatedIntegration

Integration created

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/integrations/{id}

Parameters

idintegerrequiredpath

Response

Integration

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Disconnect an integration

DELETE
https://api.nitrosend.com/v1/my/integrations/{id}

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

idintegerrequiredpath
confirmbooleanrequiredquery

Must be true to confirm the destructive action.

Response

204No Content

Integration disconnected

400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409ConflictError

The selected sender still has active or unsettled work.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update an email provider integration

PATCH
https://api.nitrosend.com/v1/my/integrations/{id}

Updates credentials or operational fields for an existing email provider. The provider cannot be changed once the integration exists.

Body

application/json
integrationMailgunIntegrationInput | SesIntegrationInput | PostmarkIntegrationInput | ResendIntegrationInput | SendgridIntegrationInput | ActiveCampaignIntegrationInputrequired
Show child attributes
One of
providerstringmailgunrequired
api_keystringrequired
domainstringrequired

Mailgun sending domain

regionstring | null

Optional Mailgun region hint

activebooleantrue
providerstringsesrequired
access_key_idstringrequired
secret_access_keystringrequired
regionstringrequired

AWS SES region

activebooleantrue
providerstringpostmarkrequired
server_tokenstringrequired

Postmark server token for sending email

account_tokenstringrequired

Postmark account token for domains API access

activebooleantrue
providerstringresendrequired
api_keystringrequired
activebooleantrue
providerstringsendgridrequired
api_keystringrequired
activebooleantrue
providerstringactivecampaignrequired
api_urlstring<uri>required

The API URL from ActiveCampaign Settings > Developer, like https://youraccount.api-us1.com. Only https on an ActiveCampaign API host is accepted.

api_keystringrequiredwrite only
activebooleantrue

Parameters

idintegerrequiredpath

Response

Integration updated

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/{id}/test

A passing first test of a contact-sync integration that has never synced (ActiveCampaign) also starts its first sync.

Parameters

idintegerrequiredpath

Response

Tested integration

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

The provider refused the connection, for example "ActiveCampaign rejected the API key".

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Set an integration as the primary provider for its category

PATCH
https://api.nitrosend.com/v1/my/integrations/{id}/primary

Parameters

idintegerrequiredpath

Response

Integration marked primary

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get an integration's versioned profile sync contract

GET
https://api.nitrosend.com/v1/my/integrations/{integration_id}/sync_configuration

Parameters

integration_idintegerrequiredpath

Response

Safe sync configuration

Response fields application/json
integration_idintegerrequired
providerstringrequired
sync_contractIntegrationSyncContractrequired
Show child attributes
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Validate and update an integration's profile sync contract

PATCH
https://api.nitrosend.com/v1/my/integrations/{integration_id}/sync_configuration

Body

application/json
sync_contractIntegrationSyncContractrequired
Show child attributes
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean

Parameters

integration_idintegerrequiredpath
confirm_deselectionbooleanfalsequery

Response

Updated safe sync configuration

Response fields application/json
integration_idintegerrequired
providerstringrequired
sync_contractIntegrationSyncContractrequired
Show child attributes
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/integrations/{integration_id}/sync_configuration/discovery

Parameters

integration_idintegerrequiredpath

Response

200OKIntegrationSyncConfiguration & object

Sync configuration and bounded provider discovery metadata

Response fields application/json
integration_idintegerrequired
providerstringrequired
sync_contractIntegrationSyncContractrequired
Show child attributes
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean
discoveryIntegrationSyncDiscoveryrequired
Show child attributes
providerstringrequired
versioninteger1required
truncatedbooleanrequired
objectsArray<object>required
Show child attributes
object_idstringrequired
object_slugstringrequired
singular_nounstring
plural_nounstring
eligiblebooleanrequired
recommended_modestring | nulladdressablerelated
ineligible_reasonstring | null
attributes_truncatedboolean
Show child attributes
attribute_idstringrequired
attribute_slugstringrequired
titlestring
typestringrequired
classificationstringcanonical_scalarfact_onlyrelationshiprequired
requiredboolean
uniqueboolean
multiselectboolean
target_object_slugsArray<string>
optionsArray<string>
Show child attributes
attribute_idstringrequired
attribute_slugstringrequired
titlestring
typestringrequired
classificationstringcanonical_scalarfact_onlyrelationshiprequired
requiredboolean
uniqueboolean
multiselectboolean
target_object_slugsArray<string>
optionsArray<string>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/attio/connect

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

200OKobject

OAuth authorize URL

Response fields application/json
authorize_urlstring<uri>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/hubspot/connect

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

200OKobject

OAuth authorize URL

Response fields application/json
authorize_urlstring<uri>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/{provider}/connect

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

application/json
sending_domain_idinteger

Optional existing brand domain to bind explicitly. A new connection without it is exact-address only.

return_tostring

Signed allowlisted app-relative return path. External origins and traversal are rejected.

integration_idinteger

Existing connection to reconnect without changing its mailbox.

Parameters

providerstringgmailmicrosoft365requiredpath

Response

200OKobject

Provider authorization URL

Response fields application/json
authorize_urlstring<uri>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/smtp/connect

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

application/json
integration_idinteger

Existing pending SMTP connection.

mailboxobjectrequired
Show child attributes
mailbox_addressstring<email>required
smtp_hoststringrequired
smtp_portinteger4655872525required
smtp_usernamestringrequired
smtp_passwordstring<password>requiredwrite only
imap_hoststringrequired
imap_portinteger993required
imap_usernamestringrequired
imap_passwordstring<password>write only

Defaults to SMTP password.

sent_folderstring
junk_folderstring

Response

Pending mailbox connection; code sent to its address.

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/{id}/verify_mailbox

Body

application/json
codestringrequired

Parameters

idintegerrequiredpath

Response

Connected exact-address mailbox.

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/integrations/{id}/smtp_feedback

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

idintegerrequiredpath

Response

SMTP feedback setup and the 20 most recent receipts.

Response fields application/json
urlstring<uri>required
signing_secretstringrequired

Connection-specific whsec_ key; never included in integration lists or broadcasts.

signing_formatstringstandard_webhooksrequired
eventsArray<object>required
Show child attributes
idstring
typestringtestdeliveredbouncedcomplained
statusstringpendingprocessingprocessedignoredfailed
received_atstring<date-time>
processed_atstring<date-time> | null
message_idstring | null
recipientstring | null
error_messagestring | null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Replace this SMTP connection's feedback signing secret

POST
https://api.nitrosend.com/v1/my/integrations/{id}/smtp_feedback/rotate

The old secret is invalid immediately. Previously authenticated receipts still process.

Parameters

idintegerrequiredpath

Response

Setup with the replacement secret.

Response fields application/json
urlstring<uri>required
signing_secretstringrequired

Connection-specific whsec_ key; never included in integration lists or broadcasts.

signing_formatstringstandard_webhooksrequired
eventsArray<object>required
Show child attributes
idstring
typestringtestdeliveredbouncedcomplained
statusstringpendingprocessingprocessedignoredfailed
received_atstring<date-time>
processed_atstring<date-time> | null
message_idstring | null
recipientstring | null
error_messagestring | null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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 signed delivery feedback for one SMTP connection

POST
https://api.nitrosend.com/hooks/smtp/{id}/events

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

application/json
One of
typestringtestrequired
typestringdeliveredbouncedcomplainedrequired
message_idstringrequired

Original RFC Message-ID, with or without surrounding angle brackets.

recipientstring<email>required
occurred_atstring<date-time>required

Outcome time, no more than five minutes in the future.

statusstring

Required 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_tokenstring

Original X-Nitro-Dispatch header, supplied together with nitrosend_message_id.

any

Parameters

idintegerrequiredpath
webhook-idstringrequiredheader

Unique event ID, stable across retries.

webhook-timestampstringrequiredheader

Unix seconds at the time this attempt is signed.

webhook-signaturestringrequiredheader

Response

200OK

Durable receipt accepted, including identical retries.

400Bad Request

Invalid JSON, fields, timestamp, event type, or event data.

403Forbidden

Unknown connection or invalid, missing, or stale signing credentials.

409Conflict

Event ID was previously used for different content.

413Payload Too Large

Body exceeds 16 KiB.

429Too Many Requests

Callback rate exceeded; retry with backoff.

500Internal Server Error

Receipt or enqueue failed; retry the same event ID.

Complete a sending mailbox connection

GET
https://api.nitrosend.com/integrations/{provider}/callback

Parameters

providerstringgmailmicrosoft365requiredpath
statestringrequiredquery
codestringrequiredquery

Response

303See Other

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

POST
https://api.nitrosend.com/v1/my/integrations/shopify/connect

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

application/json
shopifyobjectrequired
Show child attributes
shopstringrequired
Example
test-shop.myshopify.com
app_keystring

Explicit registered app identity; omitted requests resolve the existing shop registration.

Example
appstore

Response

200OKobject

OAuth authorize URL

Response fields application/json
authorize_urlstring<uri>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/shopify/credentials

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

application/json
shopifyobjectrequired
Show child attributes
shopstringrequired

Permanent myshopify.com domain or shop slug.

client_idstringrequiredwrite only

Client ID for the merchant-owned Shopify app.

client_secretstring<password>requiredwrite only

Client secret for the merchant-owned Shopify app.

Response

Existing merchant-managed Shopify connection replaced

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
201CreatedIntegration

Merchant-managed Shopify connection created

Response fields application/json
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Missing fields, invalid credentials, missing scopes, or a shop ownership conflict

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

missing_scopesArray<string>read_customersread_ordersread_products
validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/integrations/stripe/connect

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

application/json
stripeobject
Show child attributes
modestringlivetestlive

Response

200OKobject

OAuth authorize URL

Response fields application/json
authorize_urlstring<uri>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/integrations/stripe/install

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

modestringlivetestlivequery

Response

302Found

Redirect to the Stripe App install link

404Not Found

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

GET
https://api.nitrosend.com/integrations/stripe/callback

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

codestringquery
statestringquery
errorstringquery
error_descriptionstringquery

Response

302Found

Public install redirect into the app or to sign in.

303See Other

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

GET
https://api.nitrosend.com/integrations/attio/callback

Public callback endpoint used by Attio after user authorization. Verifies signed state, exchanges auth code, and finalizes Attio integration connection.

Parameters

codestringquery
statestringquery
errorstringquery
error_descriptionstringquery

Response

303See Other

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

GET
https://api.nitrosend.com/integrations/hubspot/callback

Public callback endpoint used by HubSpot after user authorization. Verifies signed state, exchanges auth code, persists the integration, and enqueues initial sync.

Parameters

codestringquery
statestringquery
errorstringquery
error_descriptionstringquery

Response

303See Other

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

GET
https://api.nitrosend.com/integrations/shopify/callback

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

codestringquery
statestringquery
shopstringquery
hmacstringquery
timestampstringquery
errorstringquery
error_descriptionstringquery

Response

302Found

Connected; public apps return to Shopify Admin, custom apps return to the Nitrosend integration

Response headers
Locationstring<uri>header
400Bad Requeststring

Invalid callback request

Response fields text/html
string
422Unprocessable Entitystring

OAuth exchange failure

Response fields text/html
string

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

POST
https://api.nitrosend.com/hooks/stripe_apps

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

application/json
object

Parameters

Stripe-Signaturestringrequiredheader

Response

200OK

Verified event acknowledged

403Forbidden

Invalid signature or unconfigured secret

500Internal Server Error

Verified event could not be enqueued

Receive an App Store Shopify webhook

POST
https://api.nitrosend.com/hooks/shopify/events

Uses the App Store app credentials when no app key is present.

Body

application/json
object

Parameters

X-Shopify-Hmac-Sha256stringrequiredheader
X-Shopify-Shop-Domainstringrequiredheader
X-Shopify-Topicstringrequiredheader

Response

200OK

Verified webhook acknowledged

400Bad Request

Invalid JSON payload

401Unauthorized

Invalid App Store HMAC

500Internal Server Error

Verified webhook could not be applied

Receive a merchant-managed Shopify webhook

POST
https://api.nitrosend.com/hooks/shopify/merchant/events

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

application/json
object

Parameters

X-Shopify-Hmac-Sha256stringrequiredheader
X-Shopify-Shop-Domainstringrequiredheader
X-Shopify-Topicstringrequiredheader
X-Shopify-Webhook-Idstringheader

Response

200OK

Verified supported webhook processed or unsupported topic safely acknowledged

400Bad Request

Verified supported webhook contained invalid JSON

401Unauthorized

Webhook could not be authenticated

500Internal Server Error

Verified webhook could not be applied

Receive a Shopify webhook for a named app

POST
https://api.nitrosend.com/hooks/shopify/events/{app_key}

Body

application/json
object

Parameters

app_keystringcustomrequiredpath
X-Shopify-Hmac-Sha256stringrequiredheader
X-Shopify-Shop-Domainstringrequiredheader
X-Shopify-Topicstringrequiredheader

Response

200OK

Verified webhook acknowledged

400Bad Request

Invalid JSON payload

401Unauthorized

Invalid app-specific HMAC

500Internal Server Error

Verified webhook could not be applied

Open or resume the embedded Shopify app

POST
https://api.nitrosend.com/integrations/shopify/session

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

200OKobject

Embedded Shopify integration opened

Response fields application/json
integration_idintegerrequired
manage_urlstring<uri> | null
requires_planbooleanrequired
redirect_tostringrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable Entityobject

Embedded install needs recovery or cannot be opened

Response fields application/json
errorstringrequired
messagestringrequired
connect_pathstring

Relative dashboard path, only present for existing_account recovery

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

GET
https://api.nitrosend.com/integrations/shopify/billing/callback

Parameters

shopstringrequiredquery

Response

302Found

Redirect back to the app in Shopify Admin

400Bad Request

Invalid Shopify shop domain

Brands

Brand context plus Brand Kit identity, theme, and per-brand configuration

List brands (paginated)

GET
https://api.nitrosend.com/v1/my/brands

Brand-scoped credentials see only their own brand. Signed-in account users see their accessible account's brands.

Parameters

pageinteger1query
perinteger<= 100100query

Response

All brands for the account

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/brands

Requires a signed-in account user. Brand-scoped credentials cannot create brands.

Body

application/json
namestring

Internal brand name; mirrors company_name when company_name is omitted

brand_colorstring
text_colorstring
bg_colorstring
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring
font_bodystring
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring
physical_addressstring
company_namestring
email_from_namestring
email_from_emailstring<email>
email_reply_tostring<email>
email_view_onlineboolean
email_view_online_placementstringtopfooter

Where the View in browser link goes: at the top of the email, or beside the footer's Unsubscribe link.

email_track_opensboolean

Inject the open-tracking pixel into this brand's emails.

email_track_clicksboolean

Rewrite this brand's links for click tracking.

test_email_recipientsArray<string>
default_headerobject
default_themeobject

Response

201CreatedBrand

Brand created

Response fields application/json
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable Entityobject | Error & object

Brand limit reached or validation failed

Response fields application/json
One of
errorbooleanrequired
codestringbrand_limit_reachedrequired

Machine-readable reason returned when the current plan cannot create another brand.

messagestringrequired
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/brands/{sid}

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKBrand

Brand

Response fields application/json
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Delete a brand

DELETE
https://api.nitrosend.com/v1/my/brands/{sid}

Parameters

sidstringrequiredpath

Brand secure identifier

forcestringtruequery

Must be true to delete a brand that has queued messages or scheduled/live campaigns.

Response

200OKBrand

Deleted brand

Response fields application/json
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>
409Conflictobject

Brand has active sends and requires explicit force confirmation

Response fields application/json
errorbooleanrequired
codestringbrand_has_active_sendsrequired
active_sendsBrandDeletionSafetyActiveSendsrequired
Show child attributes
queued_messagesinteger>= 0required
active_campaignsinteger>= 0required

Scheduled or live campaigns.

deletion_safetyBrandDeletionSafetyrequired
Show child attributes
deletion_impactBrandDeletionSafetyImpactrequired
Show child attributes
contactsinteger>= 0required
campaignsinteger>= 0required
flowsinteger>= 0required
templatesinteger>= 0required
domainsinteger>= 0required
messagesinteger>= 0required
active_sendsBrandDeletionSafetyActiveSendsrequired
Show child attributes
queued_messagesinteger>= 0required
active_campaignsinteger>= 0required

Scheduled or live campaigns.

can_deletebooleanrequired

True when no force confirmation is required.

requires_forcebooleanrequired

True when active sends require force=true to delete.

422Unprocessable EntityError

Cannot delete the only brand

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update a brand

PATCH
https://api.nitrosend.com/v1/my/brands/{sid}

Body

application/json
namestring

Internal brand name; mirrors company_name when company_name is omitted

brand_colorstring
text_colorstring
bg_colorstring
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring
font_bodystring
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring
physical_addressstring
company_namestring
email_from_namestring
email_from_emailstring<email>
email_reply_tostring<email>
email_view_onlineboolean
email_view_online_placementstringtopfooter

Where the View in browser link goes: at the top of the email, or beside the footer's Unsubscribe link.

email_track_opensboolean

Inject the open-tracking pixel into this brand's emails.

email_track_clicksboolean

Rewrite this brand's links for click tracking.

sender_identity_idinteger

Ready brand-owned email sending identity to select through the canonical sender-selection authority.

sender_local_partstring

Visible From local part for the selected sending identity.

test_email_recipientsArray<string>
default_headerobject
default_themeobject

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKBrand

Updated brand

Response fields application/json
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/brands/{sid}/prepare_sending

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

application/json
subdomainstring

Chosen subdomain label under the hosted apex; validated by the same policy as company-derived names.

local_partstring

Local part for the sender address (defaults to hello).

Parameters

sidstringrequiredpath

Brand secure identifier

Response

The brand-subdomain sender is ready

Response fields application/json
statusstringreadyunavailablerequired
brand_subdomainBrandSubdomainrequired
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

422Unprocessable EntityError

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.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

429Too Many RequestsError

Address request rate or claim allowance reached. Retry-After specifies the wait in seconds.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

The shared hosted-sender root is not release-ready; no identity or delivery state was written

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Change the brand's Nitrosend address name

POST
https://api.nitrosend.com/v1/my/brands/{sid}/rename_hosted_sender

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

application/json
subdomainstringrequired

Requested hosted address name

expected_fqdnstringrequired

Current brand_subdomain.fqdn

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKBrand

Updated brand; an exact retry returns the same address

Response fields application/json
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>
409ConflictError

The address changed, or affected delivery work is still active. Nothing was changed.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

The name is prohibited or taken, the account allowance is exhausted, or the inbox cannot preserve more addresses. Nothing was changed.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

429Too Many RequestsError

Request or claim rate exceeded. Retry-After specifies the wait in seconds.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

The shared service is unavailable. Nothing was changed.

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Check whether a Nitrosend address can be reserved

GET
https://api.nitrosend.com/v1/my/brands/{sid}/hosted_sender_availability

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

sidstringrequiredpath

Brand secure identifier

subdomainstringrequiredquery

Requested subdomain label under the hosted apex

local_partstringquery

Requested local part, checked with the same policy reservation applies; omitted means the allocator's default.

Response

Availability result

Response fields application/json
subdomainstringrequired

The normalised label that would be reserved (or the input when unsafe)

fqdnstring | null
availablebooleanrequired
reasonstring | nulltakenunsafereservedlocal_part_invalid

Why the address is unavailable; null when available

local_partstring | null

The normalised local part that would be reserved (the allocator's default when none was given), or the input when it is invalid.

from_emailstring | null

The exact address that would be reserved; null when unavailable for a policy reason

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get deletion safety for a brand

GET
https://api.nitrosend.com/v1/my/brands/{sid}/deletion_safety

Returns authoritative deletion impact counts and active-send state for the confirmation UI.

Parameters

sidstringrequiredpath

Brand secure identifier

Response

Brand deletion safety

Response fields application/json
deletion_impactBrandDeletionSafetyImpactrequired
Show child attributes
contactsinteger>= 0required
campaignsinteger>= 0required
flowsinteger>= 0required
templatesinteger>= 0required
domainsinteger>= 0required
messagesinteger>= 0required
active_sendsBrandDeletionSafetyActiveSendsrequired
Show child attributes
queued_messagesinteger>= 0required
active_campaignsinteger>= 0required

Scheduled or live campaigns.

can_deletebooleanrequired

True when no force confirmation is required.

requires_forcebooleanrequired

True when active sends require force=true to delete.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Scan a business website and apply its Brand Kit

POST
https://api.nitrosend.com/v1/my/brands/{sid}/scrape

Body

application/json
urlstringrequired

Real business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.

Parameters

sidstringrequiredpath

Brand secure identifier

Idempotency-Keystringheader

Reuse only for an exact retry of this website request.

Response

Admitted scan, including the same reference on an idempotent retry

Response fields application/json
statusstringscanningscrapingrequired
urlstringrequired
scan_idstringrequired
idempotent_replayboolean
400Bad Request

Invalid idempotency key

409Conflict

Idempotency key already used for another website

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/brands/{sid}/onboarding

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Onboarding state for the brand

Response fields application/json
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Complete a brand onboarding step

POST
https://api.nitrosend.com/v1/my/brands/{sid}/onboarding/steps

Body

application/json
stepstringbrand_kit_setupdomain_verifiedfirst_contactfirst_sendrequired

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Updated onboarding state

Response fields application/json
stepsobject
progressobject
Show child attributes
completedinteger
totalinteger
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/brands/{sid}/scrape_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

application/json
urlstringrequired

Real business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.

Parameters

sidstringrequiredpath

Brand secure identifier

Idempotency-Keystringheader

Reuse only for an exact retry of this website request.

Response

Admitted preview

Response fields application/json
statusstringscanningscrapingrequired
urlstringrequired
scan_idstringrequired
idempotent_replayboolean
400Bad Request

Invalid idempotency key

409Conflict

Idempotency key already used for another website

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/brands/{sid}/scrape_preview_status

Parameters

sidstringrequiredpath

Brand secure identifier

scan_idstringquery

Omit to recover this brand's current admitted scan. The reference survives transient progress-cache expiry.

Response

Current transient scan result

Response fields application/json
statusstringscanningcompletedfailedunknownrequired
scan_idstring | nullrequired
kindstringwebsitekit
urlstring
errorstring
previewobject
404Not FoundBrandScanStatus

Unknown or expired progress. The setup center retains any admitted reference.

Response fields application/json
statusstringscanningcompletedfailedunknownrequired
scan_idstring | nullrequired
kindstringwebsitekit
urlstring
errorstring
previewobject

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

POST
https://api.nitrosend.com/v1/my/brands/{sid}/kit_apply

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

application/json
scan_idstringrequired
fieldsobject

Selected editable Brand Kit fields. Unselected captured fields are not applied.

logo_candidate_idstring

Selected candidate from a file kit preview.

template_idstring

Selected template from a file kit preview.

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Selected kit saved atomically

Response fields application/json
brandBrandrequired
Show child attributes
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>
templateobject
409Conflict

A newer source superseded this save

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
503Service Unavailable

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

POST
https://api.nitrosend.com/v1/my/brands/{sid}/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

sidstringrequiredpath

Brand secure identifier

Idempotency-Keystringrequiredheader

Response

202Accepted

Accepted

400Bad Request

Missing idempotency key

403Forbidden

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

POST
https://api.nitrosend.com/v1/my/brands/{sid}/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

sidstringrequiredpath

Brand secure identifier

Response

Setup center state, with the welcome email's progress

Response fields application/json
next_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.

Show child attributes
idstringbrandsenderaddresscontactscustom_domainagentrequired
blockingbooleanrequired
scopestringemailcampaigns_and_flows
statestringaction_requiredrecommendedwaitingrequired
Show child attributes
idstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdns

The 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.

completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
clientstring | null

connect_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.

sectionsobject
Show child attributes
requiredArray<string>
recommendedArray<string>
progressobject

Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.

Show child attributes
completedinteger
totalinteger
seenboolean
dismissedboolean
completeboolean
establishedboolean

True 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 | null

The 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.

Show child attributes
statestringqueuedwritingsendingsentwrittenskippedfailed

written: the draft exists and Nitrosend did not send it itself (the account is not new), so a test goes through the brand's sender. skipped: not written for this brand.

campaign_idinteger | null
sent_atstring<date-time> | null
tostring | null
suggested_sitestring | null

A 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 | nullownhosted

Who a first real send comes from, once asked.

contact_sourceobject | null

The mail tools the last scan found evidence of on the brand's site.

Show child attributes
sitestring
toolsArray<string>mailchimpklaviyohubspotmailerlitebrevoactivecampaignshopify
suggested_addressobject | null

A 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.

Show child attributes
sitestring
addressstring
pagestring

Where on the site it was found, as host and path (allbirds.com/pages/contact).

first_kitbooleanread only

Whether a website read now saves itself as this brand's first Brand Kit. Once it's false, a preview waits for an explicit apply.

current_scanobject | null

The 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.

Show child attributes
scan_idstringrequired
kindstringwebsitekitbriefrequired
urlstring
started_atstring<date-time>required
statusstringscanningcompletedfailedunknownrequired
appliedbooleanrequired
errorstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get brand setup center state

GET
https://api.nitrosend.com/v1/my/brands/{sid}/setup_center

Parameters

sidstringrequiredpath

Brand secure identifier

Response

Setup center state for the brand

Response fields application/json
next_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.

Show child attributes
idstringbrandsenderaddresscontactscustom_domainagentrequired
blockingbooleanrequired
scopestringemailcampaigns_and_flows
statestringaction_requiredrecommendedwaitingrequired
Show child attributes
idstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdns

The 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.

completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
clientstring | null

connect_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.

sectionsobject
Show child attributes
requiredArray<string>
recommendedArray<string>
progressobject

Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.

Show child attributes
completedinteger
totalinteger
seenboolean
dismissedboolean
completeboolean
establishedboolean

True 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 | null

The 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.

Show child attributes
statestringqueuedwritingsendingsentwrittenskippedfailed

written: the draft exists and Nitrosend did not send it itself (the account is not new), so a test goes through the brand's sender. skipped: not written for this brand.

campaign_idinteger | null
sent_atstring<date-time> | null
tostring | null
suggested_sitestring | null

A 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 | nullownhosted

Who a first real send comes from, once asked.

contact_sourceobject | null

The mail tools the last scan found evidence of on the brand's site.

Show child attributes
sitestring
toolsArray<string>mailchimpklaviyohubspotmailerlitebrevoactivecampaignshopify
suggested_addressobject | null

A 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.

Show child attributes
sitestring
addressstring
pagestring

Where on the site it was found, as host and path (allbirds.com/pages/contact).

first_kitbooleanread only

Whether a website read now saves itself as this brand's first Brand Kit. Once it's false, a preview waits for an explicit apply.

current_scanobject | null

The 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.

Show child attributes
scan_idstringrequired
kindstringwebsitekitbriefrequired
urlstring
started_atstring<date-time>required
statusstringscanningcompletedfailedunknownrequired
appliedbooleanrequired
errorstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update brand setup center state

PATCH
https://api.nitrosend.com/v1/my/brands/{sid}/setup_center

Body

application/json

Provide one of seen, dismissed, sender_choice, or card.

seenboolean
dismissedboolean
sender_choicestringownhosted
cardstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdns
metadataobject

Parameters

sidstringrequiredpath

Brand secure identifier

Response

Updated setup center state

Response fields application/json
next_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.

Show child attributes
idstringbrandsenderaddresscontactscustom_domainagentrequired
blockingbooleanrequired
scopestringemailcampaigns_and_flows
statestringaction_requiredrecommendedwaitingrequired
Show child attributes
idstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdns

The 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.

completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
clientstring | null

connect_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.

sectionsobject
Show child attributes
requiredArray<string>
recommendedArray<string>
progressobject

Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.

Show child attributes
completedinteger
totalinteger
seenboolean
dismissedboolean
completeboolean
establishedboolean

True 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 | null

The 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.

Show child attributes
statestringqueuedwritingsendingsentwrittenskippedfailed

written: the draft exists and Nitrosend did not send it itself (the account is not new), so a test goes through the brand's sender. skipped: not written for this brand.

campaign_idinteger | null
sent_atstring<date-time> | null
tostring | null
suggested_sitestring | null

A 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 | nullownhosted

Who a first real send comes from, once asked.

contact_sourceobject | null

The mail tools the last scan found evidence of on the brand's site.

Show child attributes
sitestring
toolsArray<string>mailchimpklaviyohubspotmailerlitebrevoactivecampaignshopify
suggested_addressobject | null

A 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.

Show child attributes
sitestring
addressstring
pagestring

Where on the site it was found, as host and path (allbirds.com/pages/contact).

first_kitbooleanread only

Whether a website read now saves itself as this brand's first Brand Kit. Once it's false, a preview waits for an explicit apply.

current_scanobject | null

The 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.

Show child attributes
scan_idstringrequired
kindstringwebsitekitbriefrequired
urlstring
started_atstring<date-time>required
statusstringscanningcompletedfailedunknownrequired
appliedbooleanrequired
errorstring
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

GET
https://api.nitrosend.com/v1/my/saved_views

Returns all shared views in the current account plus the caller's own private views. Optionally filtered by surface.

Parameters

surfacestringcontactssendingactivityquery

Filter views by surface

pageinteger1query
limitinteger<= 10025query

Response

Saved views

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
Response fields application/json
Show child attributes
idinteger
surfacestringcontactssendingactivity
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

ownerboolean

True when the current user is the creator of this view

created_atstring<date-time>
updated_atstring<date-time>

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

POST
https://api.nitrosend.com/v1/my/saved_views

Creates a new saved view owned by the current user. Defaults to private visibility if not specified.

Body

application/json
surfacestringcontactssendingactivityrequired
namestringrequired
visibilitystringprivatesharedprivate

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

Response

201CreatedSavedView

Saved view created

Response fields application/json
idinteger
surfacestringcontactssendingactivity
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

ownerboolean

True when the current user is the creator of this view

created_atstring<date-time>
updated_atstring<date-time>
422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

DELETE
https://api.nitrosend.com/v1/my/saved_views/{id}

Deletes a saved view. Allowed only for the creator or the account owner. Other members receive 403.

Parameters

idintegerrequiredpath

Response

Deleted saved view

Response fields application/json
idinteger
surfacestringcontactssendingactivity
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

ownerboolean

True when the current user is the creator of this view

created_atstring<date-time>
updated_atstring<date-time>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Update a saved view

PATCH
https://api.nitrosend.com/v1/my/saved_views/{id}

Updates a saved view. Allowed only for the creator or the account owner. Other members receive 403.

Body

application/json
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

Parameters

idintegerrequiredpath

Response

Updated saved view

Response fields application/json
idinteger
surfacestringcontactssendingactivity
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

ownerboolean

True when the current user is the creator of this view

created_atstring<date-time>
updated_atstring<date-time>
403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/my/saved_views/{id}/fork

Clones an existing view (typically a shared view) into a new private view owned by the caller. The original is not modified.

Parameters

idintegerrequiredpath

Response

201CreatedSavedView

Forked saved view

Response fields application/json
idinteger
surfacestringcontactssendingactivity
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

ownerboolean

True when the current user is the creator of this view

created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/public/shopify/events

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

application/json
event_idstringrequired
event_namestringproduct_viewedproduct_added_to_cartproduct_removed_from_cartrequired
customer_idstring
emailstring<email>
phonestring
propertiesobject

Response

202Acceptedobject

Event accepted, ignored, or dropped

Response fields application/json
okbooleanrequired
outcomestringcapturedignoreddroppedrequired
event_idinteger
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

Authorization

bearerAuth

Read an anonymous flow demo

GET
https://api.nitrosend.com/v1/public/flow_demo

A demo past its scan deadline (3 minutes) or its generation deadline (8 minutes) reads as failed.

Parameters

X-Flow-Demo-Tokenstringrequiredheader

Response

Current demo state

Response fields application/json

One 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.

statusstringscanninggeneratingreadyfailedexpiredrequired
revisioninteger

Advances with each brand edit or generation retry. Absent when expired.

domainstring
goalstring
brandobject

Scanned Brand Kit fields, present once the scan has completed.

logo_urlstring

Scanned logo

flowobject

The generated draft for the current revision, present when ready.

failed_stagestringscangenerate

Present when failed. A failed scan cannot be retried; start again.

messagestring

Visitor copy, present when failed or expired.

error_codestringflow_demo_attempts_exhausted

Present when a generation failed on the demo's last attempt: it cannot be retried, and message offers an account instead.

Start an anonymous brand scan for a flow demo

POST
https://api.nitrosend.com/v1/public/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

application/json
domainstringrequired
goalstringrequired
turnstile_tokenstringrequired

Single-use Turnstile token for the flow_demo_start action

Response

202Acceptedobject

Scan started

Response fields application/json
tokenstringrequired

Opaque bearer token kept on the visitor's device

statusstringscanningrequired
revisionintegerrequired
422Unprocessable EntityError

Invalid or private website or goal (flow_demo_invalid), or a missing or failed bot check (flow_demo_bot_check_failed).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

429Too Many RequestsError

Per-IP demo start limit reached

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

503Service UnavailableError

The demo is unavailable or its daily cap is spent (flow_demo_unavailable).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Edit the scanned Brand Kit and regenerate the flow

POST
https://api.nitrosend.com/v1/public/flow_demo/review

Changed fields start one regeneration under a new revision; unchanged fields change nothing. Each demo has four generation attempts in total.

Body

application/json
fieldsobjectrequired

Parameters

X-Flow-Demo-Tokenstringrequiredheader

Response

The demo after the edit

Response fields application/json

One 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.

statusstringscanninggeneratingreadyfailedexpiredrequired
revisioninteger

Advances with each brand edit or generation retry. Absent when expired.

domainstring
goalstring
brandobject

Scanned Brand Kit fields, present once the scan has completed.

logo_urlstring

Scanned logo

flowobject

The generated draft for the current revision, present when ready.

failed_stagestringscangenerate

Present when failed. A failed scan cannot be retried; start again.

messagestring

Visitor copy, present when failed or expired.

error_codestringflow_demo_attempts_exhausted

Present when a generation failed on the demo's last attempt: it cannot be retried, and message offers an account instead.

422Unprocessable EntityError

Expired or unscanned demo, or a field that is not an editable brand field (flow_demo_invalid); no attempts left (flow_demo_attempts_exhausted).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Retry a demo that failed during generation

POST
https://api.nitrosend.com/v1/public/flow_demo/generate

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-Tokenstringrequiredheader

Response

The demo after the retry

Response fields application/json

One 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.

statusstringscanninggeneratingreadyfailedexpiredrequired
revisioninteger

Advances with each brand edit or generation retry. Absent when expired.

domainstring
goalstring
brandobject

Scanned Brand Kit fields, present once the scan has completed.

logo_urlstring

Scanned logo

flowobject

The generated draft for the current revision, present when ready.

failed_stagestringscangenerate

Present when failed. A failed scan cannot be retried; start again.

messagestring

Visitor copy, present when failed or expired.

error_codestringflow_demo_attempts_exhausted

Present when a generation failed on the demo's last attempt: it cannot be retried, and message offers an account instead.

422Unprocessable EntityError

Expired demo or a failed scan (flow_demo_invalid); no attempts left (flow_demo_attempts_exhausted).

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

Get guest-safe Flow Builder steps and triggers

GET
https://api.nitrosend.com/v1/public/flow_demo/spec

Response

200OKobject

Flow editor schema restricted to guest-authorable actions

Response fields application/json
object

Get a canonical email template for guest editing

GET
https://api.nitrosend.com/v1/public/templates/{id}

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

idstringrequiredpath
revisionstringquery

Open only the design revision shown in a published gallery preview.

Response

Canonical catalog template

Response headers
Cache-Controlstringheader
Response fields application/json
idstringrequired
revisionstring

Digest of the concrete public design.

collectionstringbrand_studies

Present for a brand concept study; originals retain their existing response shape.

studyobject
Show child attributes
brandstringrequired
conceptbooleantruerequired
adaptedboolean
source_urlstring<uri>required
namestringrequired
categorystringrequired
tagsArray<string>required
descriptionstringrequired
subjectstringrequired
preheaderstringrequired
designEmailDesignrequired

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

409Conflictobject

The requested preview revision is no longer current. The visitor can explicitly open the current version.

Response fields application/json
object

Get the email editor schema for guest editing

GET
https://api.nitrosend.com/v1/public/templates/spec

Returns the canonical component and theme schema used by the email editor.

Response

Email component schema

Response headers
Cache-Controlstringheader
Response fields application/json

Full schema for email design sections. Each component has type, description, props (with types, required flags, defaults), and tips.

versionintegerrequired
design_guidelinesstringrequired
renderer_versionstringrequired

The @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.

componentsArray<object>required
Show child attributes
typestringrequired
descriptionstringrequired
tipsArray<string>
propsobjectrequired
Show child attributes
[key: string]object
Show child attributes
typestringrequired
requiredboolean
defaultany
descriptionstring
enumArray<string>
itemsobject
Show child attributes
[key: string]object
Show child attributes
typestringrequired
descriptionstringrequired
server_ownedboolean
unset_when_emptyboolean

An empty value is allowed in a draft; delivery leaves the section out.

theme_keystring
style_attributesArray<object>required

Standard per-section style attribute registry.

Show child attributes
keystringrequired
labelstringrequired
typestringcolorspacingenumnumberbooleanrequired
applies_toanyrequired
defaultany
theme_fallbackstring
descriptionstringrequired
mininteger
maxinteger
valuesArray<string>
targetobjectrequired
Show child attributes
elstringsectioncontentshaperequired
attrstring
preview_documentobjectrequired
Show child attributes
parameterstringrequired
descriptionstringrequired
exampleobjectrequired
variablesobjectrequired

Merge variables grouped by source namespace.

Show child attributes
[key: string]Array<object>
Show child attributes
namestringrequired
descriptionstringrequired
filtersArray<object>required
Show child attributes
namestringrequired
syntaxstringrequired
descriptionstringrequired
theme_attributesArray<object>required

Brand Kit theme attribute registry (single source of truth for the editor).

Show child attributes
keystringrequired
labelstringrequired
typestringcolorfontnumberenumspacingstringimagearrayrequired
defaultany
categorystringcolorfontvisual_identityidentityrequired
slotstring
surfacesArray<string>required
mininteger
maxinteger
valuesArray<string>
optionsArray<object>
Show child attributes
valuestring
labelstring
descriptionstring
transform_tableobject
Show child attributes
[key: string]string
columnboolean
storagestring
placeholderstring
value_resolverstring
server_ownedboolean
descriptionstring

Create or update a public contact (website forms)

POST
https://api.nitrosend.com/v1/public/contacts

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

application/json
emailstring<email>required

Subscriber email address.

list_idintegerrequired

ID of a contact list owned by the brand whose public key is presented.

first_namestring | null

Optional first name written to the contact.

last_namestring | null

Optional last name written to the contact.

phonestring | null

Optional E.164 phone number written to the SMS channel if provided.

sourcestring | null

Optional free-text label, e.g. "footer-form" or "/pricing", recorded against the signup.

dataobject | null

Optional bag of custom contact data. Reserved keys are silently dropped.

Response

201Createdobject

Contact accepted

Response fields application/json
okbooleanrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>
429Too Many RequestsError

Rate limit exceeded

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get available plans

GET
https://api.nitrosend.com/v1/app

Response

200OKobject

Active plans

Response fields application/json
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
stripe_publishable_keystring | null

MCP

Model Context Protocol JSON-RPC endpoint and discovery

Probe the MCP OAuth endpoint

GET
https://api.nitrosend.com/mcp

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

401Unauthorizedobject

MCP authentication required

Response headers
WWW-Authenticatestringheader

Bearer challenge with the RFC 9728 protected-resource metadata URL

Response fields application/json
object
405Method Not Allowedobject

Authenticated GET is not supported by the MCP transport

Response fields application/json
object

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

POST
https://api.nitrosend.com/mcp

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

application/json
object

Response

200OKobject

JSON-RPC response

Response fields application/json
object

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

GET
https://api.nitrosend.com/.well-known/poppy.json

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

200OKobject

The discovery document

Response fields application/json
protocol_versionstringrequired
Example
1.0
organizationobjectrequired
Show child attributes
namestringrequired
Example
Nitrosend
domainstringrequired
Example
api.nitrosend.com
authobject
Show child attributes
scopesobject
Show child attributes
[key: string]string
scope_hintsobject
Show child attributes
[key: string]object
Show child attributes
changesstringnonereversibleirreversible
personal_databoolean
apisArray<object>required
Show child attributes
typestringrequired
Example
mcp
urlstring<uri>required
descriptionstring
extensionsobject
Show child attributes
[key: string]Array<object>
Show child attributes
versionstringrequired
404Not Found

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

POST
https://api.nitrosend.com/v1/staff/comps

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

application/json
account_idinteger
user_idinteger
emailstring<email>

Response

Partner access enabled, or already enabled

Response fields application/json
statusstringpartner_enabledalready_partnerrequired
messagestringrequired
account_idintegerrequired
emailstring | null
planstring | null

The account's current plan slug, unchanged by this call.

commercial_tierstring | null
capabilitiesArray<string>affiliate_centermanaged_clientsrequired
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError

Partner access was revoked by an admin and is not re-granted

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

List the production customer-support queue

GET
https://api.nitrosend.com/v1/operator/support_requests

Requires an nskey_live_... API key owned by an admin or staff user. Browser JWTs are rejected.

Parameters

statusstringquery
due_onlybooleanfalsequery
account_idintegerquery
brand_idintegerquery
pageinteger1query
limitinteger<= 10025query

Response

Paginated support queue

Response fields application/json
Show child attributes
idintegerrequired
account_idintegerrequired
brand_idintegerrequired
subjectstringrequired
messagestringrequired
statusstringopenwaitingresolvedrequired
follow_up_atstring<date-time> | null
resolved_atstring<date-time> | null
last_replied_atstring<date-time> | null
created_atstring<date-time>required
updated_atstring<date-time>required
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Get one production support case

GET
https://api.nitrosend.com/v1/operator/support_requests/{id}

Parameters

idintegerrequiredpath

Response

Support request, customer account, brand, and latest reply ledger state

Response fields application/json
support_requestOperatorSupportRequest & objectrequired
Show child attributes
idintegerrequired
account_idintegerrequired
brand_idintegerrequired
subjectstringrequired
messagestringrequired
statusstringopenwaitingresolvedrequired
follow_up_atstring<date-time> | null
resolved_atstring<date-time> | null
last_replied_atstring<date-time> | null
created_atstring<date-time>required
updated_atstring<date-time>required
support_transcriptstring | null
support_transcript_truncatedboolean
accountobjectrequired
brandobjectrequired
latest_replyobject | null
github_issueobject | null
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Read bounded live diagnostics for a support case

GET
https://api.nitrosend.com/v1/operator/support_requests/{id}/diagnostics

Parameters

idintegerrequiredpath

Response

200OKobject

Current sending, DNS, campaign, and message evidence

Response fields application/json
object
401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Persist a versioned customer reply draft

POST
https://api.nitrosend.com/v1/operator/support_requests/{id}/draft

Body

application/json
bodystringrequired
runx_receipt_idstring | null

Parameters

idintegerrequiredpath

Response

Draft persisted in the reply ledger

Response fields application/json
statusstringdraftedsentrequired
support_request_idintegerrequired
thread_record_idintegerrequired
draft_versionintegerrequired
draft_statestring
terminal_outcomestring | null
last_replied_atstring<date-time> | null
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Send one current versioned customer reply

POST
https://api.nitrosend.com/v1/operator/support_requests/{id}/send_reply

Delivery is fail-closed and requires confirm: true; stale draft versions are rejected by the server ledger.

Body

application/json
thread_record_idintegerrequired
draft_versionintegerrequired
confirmbooleanrequired

Parameters

idintegerrequiredpath

Response

Reply delivered

Response fields application/json
statusstringdraftedsentrequired
support_request_idintegerrequired
thread_record_idintegerrequired
draft_versionintegerrequired
draft_statestring
terminal_outcomestring | null
last_replied_atstring<date-time> | null
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

422Unprocessable EntityError & object

Validation failed

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

validation_errorsobject
Show child attributes
[key: string]Array<string>

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

POST
https://api.nitrosend.com/v1/operator/support_requests/{id}/disposition

Body

application/json
statusstringopenwaitingresolvedrequired
confirmbooleantruerequired

Explicit confirmation of the disposition mutation.

follow_up_atstring<date-time>

Required only for waiting.

Parameters

idintegerrequiredpath

Response

Updated support request

Response fields application/json
idintegerrequired
account_idintegerrequired
brand_idintegerrequired
subjectstringrequired
messagestringrequired
statusstringopenwaitingresolvedrequired
follow_up_atstring<date-time> | null
resolved_atstring<date-time> | null
last_replied_atstring<date-time> | null
created_atstring<date-time>required
updated_atstring<date-time>required
400Bad RequestError

Bad request

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

401UnauthorizedError

Not authenticated

Response headers
WWW-Authenticatestringheader
Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

403ForbiddenError

Not authorized

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Chat Sessions

List persisted chat sessions

GET
https://api.nitrosend.com/v1/my/chat_sessions

Parameters

pageinteger1query
limitinteger<= 10025query

Response

Paginated list of chat sessions

Response headers
X-Total-Countintegerheader
X-Total-Pagesintegerheader
X-Page-Numberintegerheader
X-Next-Pageintegerheader
X-Prev-Pageintegerheader
Response fields application/json
Show child attributes
idinteger
account_idinteger
brand_idinteger
titlestring
statusstringactiveclosedfailed
started_atstring<date-time>
last_message_atstring<date-time>
message_countinteger
created_atstring<date-time>
updated_atstring<date-time>

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

GET
https://api.nitrosend.com/v1/my/chat_sessions/{id}

Parameters

idintegerrequiredpath

Response

Chat session

Response fields application/json
idinteger
account_idinteger
brand_idinteger
titlestring
statusstringactiveclosedfailed
started_atstring<date-time>
last_message_atstring<date-time>
message_countinteger
created_atstring<date-time>
updated_atstring<date-time>
Show child attributes
idinteger
rolestringuserassistanttoolsystem
contentstring

Credential-shaped values are redacted before display.

tool_callsArray<object>
Show child attributes
idstring
namestring
inputobject
safeboolean
statusstringpendingapprovedexecutingcompletedrejectederrorcancelleduncertain
approval_tokenstring

Binds a proposal to its execution and exact arguments. Commands also require the originating authenticated user.

resultany

Recorded tool outcome; queued does not mean sent.

actionsArray<object>
attachmentsArray<object>

Images the person added to the message, from the brand's image library.

Show child attributes
urlstring<uri>

The image's library URL.

filenamestring
content_typestringimage/pngimage/jpegimage/webp
widthinteger | null
heightinteger | null
sequenceinteger
created_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Close an active persisted chat session

PATCH
https://api.nitrosend.com/v1/my/chat_sessions/{id}/close

A request from an embedded Shopify session closes only a session that session's install started; any other session answers 404.

Parameters

idintegerrequiredpath

Response

Closed chat session

Response fields application/json
idinteger
account_idinteger
brand_idinteger
titlestring
statusstringactiveclosedfailed
started_atstring<date-time>
last_message_atstring<date-time>
message_countinteger
created_atstring<date-time>
updated_atstring<date-time>
404Not FoundError

Resource not found

Response fields application/json
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable 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.

Models

WorkspaceRoute

object
namestringrequired
paramsobject
queryobject

WorkspaceAttentionItem

object
keystringrequired
titlestringrequired
detailstringrequired
statestringaction_requiredworkingrequired
blockingbooleanrequired
updated_atstring<date-time>required
toWorkspaceRoute | nullrequired
Show child attributes
One of
namestringrequired
paramsobject
queryobject
null
actionstringrequired
hrefstring
progressobject
dismissibleboolean
chat_session_idinteger
priorityinteger

Account-wide restrictions use 0 and precede individual tasks.

recovery_actionsArray<object>

Existing recovery actions for this restriction; opening one never approves or resumes sending.

Show child attributes
typestringrequired
labelstringrequired
urlstringrequired

WorkspaceActivityItem

object
idintegerrequired
sourcestringmcpnitrollmapirequired
titlestringrequired
outcomestringokincompleteacceptedstreameddeniederrorhttp_errorunknownrequired
clientstring | nullrequired
created_atstring<date-time>required
toWorkspaceRoute | nullrequired
Show child attributes
One of
namestringrequired
paramsobject
queryobject
null

OperatorSupportRequest

object
idintegerrequired
account_idintegerrequired
brand_idintegerrequired
subjectstringrequired
messagestringrequired
statusstringopenwaitingresolvedrequired
follow_up_atstring<date-time> | null
resolved_atstring<date-time> | null
last_replied_atstring<date-time> | null
created_atstring<date-time>required
updated_atstring<date-time>required

OperatorSupportCase

object
support_requestOperatorSupportRequest & objectrequired
Show child attributes
idintegerrequired
account_idintegerrequired
brand_idintegerrequired
subjectstringrequired
messagestringrequired
statusstringopenwaitingresolvedrequired
follow_up_atstring<date-time> | null
resolved_atstring<date-time> | null
last_replied_atstring<date-time> | null
created_atstring<date-time>required
updated_atstring<date-time>required
support_transcriptstring | null
support_transcript_truncatedboolean
accountobjectrequired
brandobjectrequired
latest_replyobject | null
github_issueobject | null

OperatorReplyDraft

object
statusstringdraftedsentrequired
support_request_idintegerrequired
thread_record_idintegerrequired
draft_versionintegerrequired
draft_statestring
terminal_outcomestring | null
last_replied_atstring<date-time> | null

TimelineEntry

object

One normalised, whitelisted entry in a contact's unified timeline.

idstringrequired

Stable composite id, e.g. "event-123".

kindstringeventactivitylifecyclemessagerequired
typestringrequired

Event/activity/lifecycle type, e.g. checkout, opened, flow_exit.

titlestringrequired

Human-readable label for the entry.

occurred_atstring<date-time>required
metaobjectrequired

Display-only extras (e.g. amount, resource_name). Flow exits include the flow name in resource_name and its exit_event. No internal fields.

EnterpriseRequestInput

object
monthly_emailsinteger | string | null

Emails 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.

Show child attributes
One of
integer[0, 1000000000]
string
null
needsArray<string> | nullvolume_pricingdedicated_ipseats_or_domainssecurity_reviewinvoicingmigration
messagestring | null

EnterpriseRequestReceipt

object
receivedbooleanrequired
replayedbooleanrequired

True when this is the member's request from earlier today.

requestobjectrequired
Show child attributes
idintegerrequired
received_atstring<date-time>required
requester_emailstring<email>required

Where the team will reply.

SafetyRecoveryAction

object
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

SendRefusalDetail

object

Present 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_denied
how_to_fixstring

The 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.

categorystring

The 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_promptstring

The reason and fix as one paragraph to paste to an agent. Names IDs only, never text from the email.

Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject
Show child attributes
imagesArray<object>

Each image that couldn't be loaded.

Show child attributes
urlstring

The image address

problemstringnot_foundrefusedrejectedserver_errorunreachableprivate_hostunsupported_typetoo_largetoo_many_pixelsunreadablenot_a_web_addressunsupported_inline_image
http_statusinteger

The image host's HTTP status

changesArray<object>

Other changes the email needs before it can be checked.

Show child attributes
codestring
fixstring
review_idinteger

The held or blocked case, for a request to the team.

model_reasonstring

The safety check's own reason, for trusted accounts only.

Error

object
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether retrying the same idempotent operation can succeed.

retry_atstring<date-time>

Earliest recommended retry time for a retryable failure.

SignupPromoResult

object
appliedbooleanrequired

Whether the code was redeemed.

reasonstringappliedblanknot_foundnot_redeemableplan_not_foundpartner_access_revokedrequired
partnerbooleanrequired

True when the code made the account a partner (Affiliates tab and Client Management). Partner codes never change the plan.

plan_grantedbooleanrequired

True only when a referral code granted a plan.

plan_pendingboolean

True when an optional partner plan offer is being applied after signup.

StaffPartnerGrantResult

object
statusstringpartner_enabledalready_partnerrequired
messagestringrequired
account_idintegerrequired
emailstring | null
planstring | null

The account's current plan slug, unchanged by this call.

commercial_tierstring | null
capabilitiesArray<string>affiliate_centermanaged_clientsrequired

SignupVerificationRequired

object
statusstringverification_requiredrequired
error_codestringverification_required
next_actionstringverify_emailrequired
messagestringrequired
errorboolean
codeinteger
verification_expires_ininteger
Example
1800

SignupSession

object
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>
metaobject
Show child attributes
account_idinteger | null
Show child attributes
appliedbooleanrequired

Whether the code was redeemed.

reasonstringappliedblanknot_foundnot_redeemableplan_not_foundpartner_access_revokedrequired
partnerbooleanrequired

True when the code made the account a partner (Affiliates tab and Client Management). Partner codes never change the plan.

plan_grantedbooleanrequired

True only when a referral code granted a plan.

plan_pendingboolean

True when an optional partner plan offer is being applied after signup.

User

object
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
email_verified_atstring<date-time> | null

Actual email proof time; legacy access does not fabricate proof.

unconfirmed_emailstring<email> | null

Requested email change awaiting proof. Continue signing in with email until confirmation.

signup_completed_atstring<date-time> | null
mobilestring | null
country_codestring | null
time_zonestring | null
adminboolean
ui_login_countinteger

Capped 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>

Impersonator

object
idinteger
emailstring<email>
namestring | null

ImpersonationStatus

object
impersonatingbooleanrequired
impersonatorImpersonator | nullrequired
Show child attributes
One of
idinteger
emailstring<email>
namestring | null
null

ImpersonationExit

object
redirect_urlstring<uri>required
Example
https://api.nitrosend.com/adm

ManagedAccountLifecycleStatus

string

setup is a claimed client on the unpaid Setup plan whose manager access is active; it is never reported as active until the client pays.

ManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueended

ManagedAccountLifecycleStatusFilter

string
ManagedAccountLifecycleStatusFilterpreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedneeds_setup

ManagedAccountProvisioning

object
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required

ManagedAccountProvisioningCreated

object
idintegerrequired
external_refstringrequired
sourcestringdashboardpartner_apirequired
statusManagedAccountLifecycleStatuspreparingawaiting_ownerpayment_requiredsetupactivepayment_issueendedrequired

setup 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_v1required
allowed_actionsArray<string>send_invitationresend_invitationsend_payment_reminderenterreleaserequired
managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired
managed_on_setupbooleanrequired

The 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_paidbooleanrequired

The 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.

ownerobjectrequired
Show child attributes
emailstring<email>required
invitationobjectrequired
Show child attributes
expiredbooleanrequired
expires_atstring<date-time>required
deadline_atstring<date-time>required
notice_sent_atstring<date-time> | nullrequired
claimed_atstring<date-time> | nullrequired
reissues_remaininginteger[0, 3]required
created_atstring<date-time>required
updated_atstring<date-time>required
idempotent_replaybooleanrequired

DashboardManagedAccountCreateRequest

object
managed_accountobjectrequired
Show child attributes
owner_emailstring<email>required
owner_first_namestring
owner_last_namestring
account_namestringrequired

PartnerManagedAccountCreateRequest

object
managed_accountobjectrequired
Show child attributes
external_refstringrequired
owner_emailstring<email>required
owner_first_namestring
owner_last_namestring
account_namestringrequired

AccountProvisioningCredential

object
idintegerrequired
namestringrequired
scopesArray<string>provisionmanagerequired
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required

AccountProvisioningCredentialIssued

object
idintegerrequired
namestringrequired
scopesArray<string>provisionmanagerequired
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
secretstringrequiredwrite only

One-time nspk_live_ credential secret.

AccountProvisioningCredentialCreateRequest

object
credentialobjectrequired
Show child attributes
namestringrequired
scopesArray<string>provisionmanagerequired
expires_atstring<date-time>

AccountManagementCredential

object
idintegerrequired
account_management_grant_idintegerrequired
namestringrequired
permission_setstringoperator_v1required
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
brandobjectrequired
Show child attributes
idintegerrequired
sidstringrequired
namestringrequired

AccountManagementCredentialIssued

object
idintegerrequired
account_management_grant_idintegerrequired
namestringrequired
permission_setstringoperator_v1required
secret_hintstringrequired
expires_atstring<date-time>required
last_used_atstring<date-time> | null
revoked_atstring<date-time> | null
created_atstring<date-time>required
brandobjectrequired
Show child attributes
idintegerrequired
sidstringrequired
namestringrequired
secretstringrequiredwrite only

One-time nsmc_live_ credential secret.

AccountManagementCredentialCreateRequest

object
credentialobjectrequired
Show child attributes
namestringrequired
brand_sidstring

Defaults to the managed Account's default Brand.

expires_atstring<date-time>

Defaults to 90 days and cannot exceed one year.

ManagedAccountClaimRequest

object
claimobjectrequired
Show child attributes
tokenstringrequiredwrite only

ManagedAccountClaimCompletionRequest

object
claimobjectrequired
Show child attributes
tokenstringrequiredwrite only

ManagedAccountClaimInspection

object
managerobjectrequired
Show child attributes
namestring | null
managed_accountobjectrequired
Show child attributes
namestring | null
owner_emailstringrequired

Masked owner address

expires_atstring<date-time>required
authenticationstringrequired

ManagedAccountClaimCompletion

object
claimedbooleanrequired
statusstringpayment_requiredactivemanager_disabledrequired

The agency's management access. active on Setup mode does not mean paid; read payment_required.

payment_requiredbooleanrequired

The 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_setupbooleanrequired

The client account is on Setup mode.

managed_accountobjectrequired
Show child attributes
idintegerrequired
namestring | nullrequired

Account

object
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>

AccountBilling

object

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

DelegatedAccountBilling

object

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired

SendingPause

object

What 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_pausedbooleantruerequired
reasonstringcritical_bounce_ratecritical_complaint_rate

Present only for an explained deliverability pause.

occurred_atstring<date-time>required
headlinestringrequired
detailstringrequired
what_to_doArray<string>

Present only for an explained deliverability pause.

request_reviewstringrequired

The instruction an agent relays to the owner.

recovery_actionsArray<object>required
Show child attributes
typestringverify_listrequest_reviewcontact_supportrequired
labelstringrequired
urlstringrequired

App link or support mailto.

AccountResourceUsage

object
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired

AccountAccess

object
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement

AccountManagementGrant

object
idintegerrequired
statusstringpendingactiverevokedreleasedrequired
permission_setstringoperator_v1required
manager_accountobjectrequired
Show child attributes
idintegerrequired
namestring | null
requested_atstring<date-time>required
activated_atstring<date-time> | null
revoked_atstring<date-time> | null
released_atstring<date-time> | null

AccountManagementGrantCommand

object
management_grant_idintegerrequired

Exact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.

AccountTeam

object
accountAccount
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>
Show child attributes
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>
Show child attributes
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
accessible_accountsArray<Account>
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterprise

The 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_enabledboolean
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
billingAccountBilling | DelegatedAccountBilling

Owners, 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.

Show child attributes
One of

Billing for direct access (owners, admins and members, and their own credentials).

access_policystring | nullfree_allowedpaid_requiredrequired
plan_namestring | null
planPlan | null
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
spend_cap_monthly_centsinteger | null>= 0
compedboolean
overageobject
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
resourcesobject
Show child attributes
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
Show child attributes
usedintegerrequired
allowanceinteger | nullrequired
remaininginteger | nullrequired
overage_ratenumberrequired
modestringbudgetmonthlyunlimitedrequired
budgetinteger | nullrequired
budget_usedintegerrequired
fundingobjectrequired
provider_routeobjectrequired
removable_brandingboolean

Whether this account may take the Nitrosend footer off its emails, whatever allows it (plan, add-on or waiver).

outstanding_invoiceobject | null

Present 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.

Show child attributes
idinteger | null

The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

brandsobjectrequired

Per-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.

Show child attributes
usedinteger
limitinteger

Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.

remaininginteger | null

Null when unlimited is true.

unlimitedboolean
can_createboolean

True when plan headroom allows creating another brand.

domainsobject

Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.

Show child attributes
limitinteger | nullrequired
usedintegerrequired
remaininginteger | nullrequired
unlimitedbooleanrequired
can_addbooleanrequired
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger

Billing 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_requiredrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
subscription_statusstring | nullpendingactiveinactivecanceledfree_tierrequired
commercial_tierstringunsubscribedfreesetupstarterprogrowthscaleultraenterpriserequired
provider_routeobjectrequired
teamobject

Present for direct access and omitted from delegated account projections.

Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>

AccountMembership

object
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>

AccountInvite

object
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

Subscription

object
idinteger
plan_idinteger
plan_namestring | null

Current package name. Historical purchase labels are retained in billing records.

billing_providerstring | nullshopifystripestripe_projectsvercelaws
source_billing_providerstring | nullshopifystripestripe_projectsvercelaws
billing_migration_requiredboolean
manage_urlstring<uri> | null
spend_cap_monthly_centsinteger | null>= 0

Merchant-selected monthly cap for metered usage charges.

shopify_usage_meteredboolean

Whether the active Shopify plan has at least one configured usage meter.

statusstringpendingactiveinactivecanceledfree_tier
intervalstringmonthyearweekday
currencystring
subtotal_centsinteger
tax_centsinteger
total_centsinteger
base_price_centsinteger
discount_centsinteger

Per-period Stripe discount in cents (0 when none).

next_payment_centsinteger

Amount billed next period

discount_end_atstring<date-time> | null

When the discount stops (null for forever/once or no discount).

activatedboolean
Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

BillingEntitlements

object
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

AgentInboxEntitlement

object
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

SubscriptionCreateRequest

object
plan_idintegerrequired
stripe_tokenstring | null

Stripe card token for paid-plan creation.

coupon_codestring | null

Customer-entered Stripe promotion code or coupon ID. Refused on an agency operator's purchase for a client account.

DelegatedSubscription

object

What 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.

idintegerrequired
plan_idintegerrequired
plan_namestring | nullrequired
statusstringpendingactiveinactivecanceledfree_tierrequired
intervalstringmonthyearweekdayrequired
currencystringrequired
activatedbooleanrequired
base_price_centsintegerrequired
billing_providerstring | nullshopifystripestripe_projectsvercelawsrequired
source_billing_providerstring | nullshopifystripestripe_projectsvercelawsrequired
billing_routeobjectrequired
planPlan | nullrequired
Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

FundingPurchaseCreateRequest

object
amount_centsinteger>= 1required

Integer service value in minor currency units.

currencystring
instrumentstringstripe_checkoutshopify_one_time

Optional hosted funding instrument. Omit to use the account default.

paid_action_intent_idstring | null

Optional opaque continuation bound to this funding purchase.

FundingInstrument

object
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null

FundingUrlApproval

object
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired

FundingChallengeApproval

object
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null

FundingApproval

object
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null

FundingPurchase

object
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required

FundingPurchaseCapability

object
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required

FundingStatus

object
statestringrequired
applies_tostringprepaid_featuresrequired
subscription_gatebooleanrequired
currencystringrequired
available_centsintegerrequired
reserved_centsintegerrequired
deficit_centsintegerrequired
Show child attributes
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required
pending_purchaseFundingPurchase | null
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required

FundingPurchaseResponse

object
purchaseFundingPurchaserequired
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required
fundingFundingStatusrequired
Show child attributes
statestringrequired
applies_tostringprepaid_featuresrequired
subscription_gatebooleanrequired
currencystringrequired
available_centsintegerrequired
reserved_centsintegerrequired
deficit_centsintegerrequired
Show child attributes
availablebooleanrequired
statestringrequired
reasonstring | null
default_instrumentstring | nullstripe_checkoutshopify_one_time
instrumentsArray<FundingInstrument>required
Show child attributes
instrumentstringstripe_checkoutshopify_one_timerequired
providerstringstripeshopifyrequired
modestringhosted_approvalrequired
availablebooleanrequired
reasonstring | null
currencystringrequired
minimum_centsinteger | null
maximum_centsinteger | null
preset_centsArray<integer>required
pending_purchaseFundingPurchase | null
Show child attributes
idintegerrequired
paid_action_intent_idstring | null
providerstringstripeshopifyrequired
instrumentstringstripe_checkoutshopify_one_timestripe_off_sessionrequired
statusstringrequestedpendingcheckout_createdcreditedfailedexpiredpartially_reversedreversedrequired
currencystringrequired
requested_centsinteger>= 1required
requested_displaystring
checkout_urlstring<uri> | null
approvalFundingUrlApproval | FundingChallengeApproval | null
Show child attributes
One of
kindstringurlrequired
providerstringstripeshopifyrequired
urlstring<uri>required
targetstringselftoprequired
kindstringchallengerequired
instrumentstringrequired
protocolstringrequired
challengestringrequired
expires_atstring<date-time> | null
expires_atstring<date-time> | null
credited_centsinteger>= 0required
reversed_centsinteger>= 0required
created_atstring<date-time>required
updated_atstring<date-time>required

SubscriptionChangeRequest

object
plan_idintegerrequired
coupon_codestring | null

Customer-entered Stripe promotion code or coupon ID.

SubscriptionCouponPreviewRequest

object
plan_idintegerrequired
coupon_codestringrequired

Customer-entered Stripe promotion code or coupon ID.

SubscriptionCouponPreview

object
codestringrequired
discount_labelstringrequired
discount_centsintegerrequired
subtotal_centsintegerrequired
tax_centsintegerrequired
total_centsintegerrequired
total_after_discount_centsintegerrequired
currencystringrequired

OAuthPopupAccount

object
idintegerrequired
namestringrequired
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
can_manageboolean
has_campaignboolean

Whether the account has made any campaign. This alone does not determine onboarding eligibility.

setup_brandobject | null

Optional 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.

Show child attributes
sidstringrequired
suggested_sitestring | null
brand_colorstringrequired
needs_subscribebooleanrequired

Offers available through this account's provider, including retained Free terms when eligible.

Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

OAuthPopupPlan

object
idintegerrequired
namestringrequired
slugstringrequired
base_price_centsintegerrequired
intervalstring | null
tier_groupstring

OAuthPopupContext

object
application_namestring | null
emailstring

The signed-in person's address, where an agent's first test goes.

accountsArray<OAuthPopupAccount>required
Show child attributes
idintegerrequired
namestringrequired
Show child attributes
sourcestringownermembershipplatform_admindelegatedmanagement_credentialapi_keyshopifyrequired
delegatedbooleanrequired
manager_account_idinteger
manager_account_namestring | null
management_grant_idinteger
permission_setstringoperator_v1
credential_typestringmanagement
can_manageboolean
has_campaignboolean

Whether the account has made any campaign. This alone does not determine onboarding eligibility.

setup_brandobject | null

Optional 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.

Show child attributes
sidstringrequired
suggested_sitestring | null
brand_colorstringrequired
needs_subscribebooleanrequired

Offers available through this account's provider, including retained Free terms when eligible.

Show child attributes
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired
Show child attributes
idintegerrequired
namestringrequired
slugstringrequired
base_price_centsintegerrequired
intervalstring | null
tier_groupstring
stripe_publishable_keystring | null

OAuthPopupSubscribeRequest

object
plan_idintegerrequired
account_idinteger | null
stripe_tokenstring | null

OAuthPopupSubscribeResponse

object
next_stepstringconsentrequired

FirstTouchAttributionContext

object

Optional 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 | null
referrer_urlstring | null
captured_atstring<date-time> | null
utm_sourcestring | null
utm_mediumstring | null
utm_campaignstring | null
utm_contentstring | null
utm_termstring | null
fbclidstring | null

Meta click identifier (fbclid) from the first touch, subject to the click-identifier rules above.

ttclidstring | null

TikTok click identifier (ttclid) from the first touch, subject to the click-identifier rules above.

OAuthLaunchRequest

object
providerstringgoogle_oauth2githubrequired
auth_intentstringappagentapp
auth_stepstringloginsignuplogin
resume_urlstring<uri> | null

Required when auth_intent=agent; must point to the frontend /oauth/connect route.

invite_tokenstring | null
referral_codestring | null
rewardful_referral_idstring | null
attribution_contextFirstTouchAttributionContext

Optional 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.

Show child attributes
landing_urlstring | null
referrer_urlstring | null
captured_atstring<date-time> | null
utm_sourcestring | null
utm_mediumstring | null
utm_campaignstring | null
utm_contentstring | null
utm_termstring | null
fbclidstring | null

Meta click identifier (fbclid) from the first touch, subject to the click-identifier rules above.

ttclidstring | null

TikTok click identifier (ttclid) from the first touch, subject to the click-identifier rules above.

signup_intentSignupIntent | nullagency

Optional. 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

string

Optional. 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 | nullagency

OAuthLaunchResponse

object
launch_urlstring<uri>required

Brand

object
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
radiusinteger | null[0, 64]
spacing_densitystring | nullcompactnormalspacious
font_headingstring | null
font_bodystring | null
heading_sizeinteger | null[12, 48]
body_sizeinteger | null[12, 20]
brand_documentstring | null
company_descriptionstring | null
default_headerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
from_email_domain_statusstringblankverifiedunverified

Authorization state of the configured visible From address.

effective_from_emailstring<email> | nullread only
effective_reply_tostring<email> | nullread only
effective_sending_domainstring | nullread only
effective_source_emailstring<email> | nullread only
sender_configuredbooleanread only
email_view_onlineboolean

Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

email_view_online_placementstringtopfooter

Where 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_opensboolean

Default-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_clicksboolean

Default-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_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
brand_subdomainBrandSubdomain | null
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

byo_routingobject

Warns 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.

Show child attributes
mismatchboolean
providerstring | null

The connected BYO provider, e.g. ses.

bypassing_domainsArray<string>

Verified domains still sending through Nitrosend's hosted provider.

messagestring | null
subscribed_contacts_countinteger

Count 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 only
logo_tonestring | nulllightdarkread only

Measured from the logo. A light mark on transparent gets a header band in emails.

logo_aspectnumber | nullread only

The logo's width over its height. Emails fit the logo to one header height.

screenshot_urlstring<uri> | nullread only
capabilitiesobject
sms_provisionedbooleanread only
created_atstring<date-time>
updated_atstring<date-time>

BrandSubdomain

object
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

BrandSubdomainPreparationResponse

object
statusstringreadyunavailablerequired
brand_subdomainBrandSubdomainrequired
Show child attributes
namespace_statusstringunreservedactivereplacement_pendingretiringretiredrequired
statusstringbrand_identity_requiredbrand_identity_review_requirednamespace_reservation_requirednot_materializedroot_unavailablereadyunavailablerequired
readybooleanrequired
selectedboolean
preparation_requiredbooleanrequired
from_emailstring<email>
fqdnstring
apexstring
local_partstring
local_part_editableboolean
fqdn_changeableboolean

Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

suggested_subdomainstring | null

Candidate 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.

messagestring

Only with status: brand_identity_required: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

AudienceReachFit

object
plan_idintegerrequired
slugstringrequired
namestringrequired
tier_groupstringrequired
daily_capinteger | null

Recipients per 24 hours at the account's sending standing; null when unlimited

capacityinteger | null

Emails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited

days_to_reachinteger | null

Days until everyone has been reached once; null when the month cannot hold the send

coversbooleanrequired

Whether one full send to the audience fits within the month

AudienceReach

object
audienceintegerrequired
cohortstringrequired

The account's deliverability cohort the daily caps are read at

currentAudienceReachFit | null

The current plan; null when the account has no subscription

Show child attributes
plan_idintegerrequired
slugstringrequired
namestringrequired
tier_groupstringrequired
daily_capinteger | null

Recipients per 24 hours at the account's sending standing; null when unlimited

capacityinteger | null

Emails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited

days_to_reachinteger | null

Days until everyone has been reached once; null when the month cannot hold the send

coversbooleanrequired

Whether one full send to the audience fits within the month

recommendedAudienceReachFit | null

The 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

Show child attributes
plan_idintegerrequired
slugstringrequired
namestringrequired
tier_groupstringrequired
daily_capinteger | null

Recipients per 24 hours at the account's sending standing; null when unlimited

capacityinteger | null

Emails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited

days_to_reachinteger | null

Days until everyone has been reached once; null when the month cannot hold the send

coversbooleanrequired

Whether one full send to the audience fits within the month

coveredbooleanrequired

Whether the current plan covers a full send

summarystring | null

The one sentence every surface shows; null when covered

HostedSenderAvailability

object
subdomainstringrequired

The normalised label that would be reserved (or the input when unsafe)

fqdnstring | null
availablebooleanrequired
reasonstring | nulltakenunsafereservedlocal_part_invalid

Why the address is unavailable; null when available

local_partstring | null

The normalised local part that would be reserved (the allocator's default when none was given), or the input when it is invalid.

from_emailstring | null

The exact address that would be reserved; null when unavailable for a policy reason

BrandDeletionSafetyImpact

object
contactsinteger>= 0required
campaignsinteger>= 0required
flowsinteger>= 0required
templatesinteger>= 0required
domainsinteger>= 0required
messagesinteger>= 0required

BrandDeletionSafetyActiveSends

object
queued_messagesinteger>= 0required
active_campaignsinteger>= 0required

Scheduled or live campaigns.

BrandDeletionSafety

object
deletion_impactBrandDeletionSafetyImpactrequired
Show child attributes
contactsinteger>= 0required
campaignsinteger>= 0required
flowsinteger>= 0required
templatesinteger>= 0required
domainsinteger>= 0required
messagesinteger>= 0required
active_sendsBrandDeletionSafetyActiveSendsrequired
Show child attributes
queued_messagesinteger>= 0required
active_campaignsinteger>= 0required

Scheduled or live campaigns.

can_deletebooleanrequired

True when no force confirmation is required.

requires_forcebooleanrequired

True when active sends require force=true to delete.

AffiliateCenterPayload

object
enrolledbooleanrequired

Whether the account is linked to a Rewardful affiliate.

availablebooleanrequired

Whether live affiliate data or setup is currently available.

statestring | nullactivepausedunavailable
setup_statusstring | nullpendingneeds_detailsunavailable

Present only while an entitled, unlinked account is being reconciled.

share_urlstring<uri> | null
statsobject
Show child attributes
visitorsinteger>= 0
leadsinteger>= 0
conversionsinteger>= 0
earningsobject
Show child attributes
knownboolean
total_centsinteger | null
currencystring

BrandWebsiteInput

object
urlstringrequired

Real business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.

BrandScanAdmission

object
statusstringscanningscrapingrequired
urlstringrequired
scan_idstringrequired
idempotent_replayboolean

BrandScanStatus

object
statusstringscanningcompletedfailedunknownrequired
scan_idstring | nullrequired
kindstringwebsitekit
urlstring
errorstring
previewobject

SetupCenterPayload

object
next_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.

Show child attributes
idstringbrandsenderaddresscontactscustom_domainagentrequired
blockingbooleanrequired
scopestringemailcampaigns_and_flows
statestringaction_requiredrecommendedwaitingrequired
Show child attributes
idstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdns

The 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.

completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
clientstring | null

connect_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.

sectionsobject
Show child attributes
requiredArray<string>
recommendedArray<string>
progressobject

Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.

Show child attributes
completedinteger
totalinteger
seenboolean
dismissedboolean
completeboolean
establishedboolean

True 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 | null

The 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.

Show child attributes
statestringqueuedwritingsendingsentwrittenskippedfailed

written: the draft exists and Nitrosend did not send it itself (the account is not new), so a test goes through the brand's sender. skipped: not written for this brand.

campaign_idinteger | null
sent_atstring<date-time> | null
tostring | null
suggested_sitestring | null

A 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 | nullownhosted

Who a first real send comes from, once asked.

contact_sourceobject | null

The mail tools the last scan found evidence of on the brand's site.

Show child attributes
sitestring
toolsArray<string>mailchimpklaviyohubspotmailerlitebrevoactivecampaignshopify
suggested_addressobject | null

A 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.

Show child attributes
sitestring
addressstring
pagestring

Where on the site it was found, as host and path (allbirds.com/pages/contact).

first_kitbooleanread only

Whether a website read now saves itself as this brand's first Brand Kit. Once it's false, a preview waits for an explicit apply.

current_scanobject | null

The 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.

Show child attributes
scan_idstringrequired
kindstringwebsitekitbriefrequired
urlstring
started_atstring<date-time>required
statusstringscanningcompletedfailedunknownrequired
appliedbooleanrequired
errorstring

SetupCenterCard

object
idstringbrand_kit_scanimport_subscribersfirst_emailconnect_agentdns

The 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.

completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
clientstring | null

connect_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

object
idintegerrequired
keystringrequired

Dot-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).

categorystringcontactcustomenrichmentengagementtagrequired

Derived from the key namespace.

  • contact — typed column on the contacts table
  • tag — data.tags array
  • enrichment — reserved enrichment namespaces such as data.apollo.*, data.pdl.*, data.attio.*, data.hubspot.*, data.stripe.*, data.shopify.*, and derived data.nitro.*
  • custom — any other data.* key
  • engagement — future engagement traits (reserved)
field_typestringstringnumberbooleandateenumrequired

Inferred from the first observed value; pinned and never flipped.

presentation_typestringtextnumbercurrencypercentdatedatetimebooleanenumrequired

Shared presentation contract used by fact displays and generated merge tags.

presentation_optionsobjectrequired

Provider-supplied formatting metadata such as decimal precision, currency-code field path, unit scale, or percentage multiplier.

labelstringrequired

Human-readable label. Defaults to a humanised version of the key.

display_labelstring

Source-qualified field label suitable for display.

source_keystring | null
source_namestring | null
object_labelstring | null
source_field_labelstring | null
merge_tagstring | null

Ready-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.

promotedbooleanrequired

Whether this field is pinned as a default column in the contacts grid.

fill_ratestring | null

Percentage of contacts that have a non-null value for this field. Computed asynchronously; may be null if the refresh job has not run yet.

Example
75.0
fill_rate_refreshed_atstring<date-time> | null

When fill_rate was last computed.

created_atstring<date-time>
updated_atstring<date-time>

DeliveryCapacity

object
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required

SharedAbuseCapacity

object

Retired shared probation allowance. Status is always not_applicable; the field remains for compatibility.

statusstringavailabledeferrednot_applicableunknowndegradedrequired
reason_codestring
retry_atstring<date-time>

DeliveryPacingScope

object
typestringrequired
keystring
statusstringreadydeferredrequired
next_dispatch_atstring<date-time>
minimum_interval_secondsnumber>= 0required
baseline_rate_per_secondnumber>= 0
effective_rate_per_secondnumber>= 0
cooldown_reasonstring
cooldown_untilstring<date-time>
feedback_epochinteger>= 0required

DeliveryPacingState

object
statusstringreadydeferredrequired
policy_versionstringrequired
queued_quantityinteger>= 0
next_dispatch_atstring<date-time>
shared_senderSharedSenderStatus
Show child attributes
statusstringreadydeferredpauseddegradedrequired
reason_codestringshared_sender_rate_limitedshared_sender_provider_backpressureshared_sender_evidence_pending
retry_atstring<date-time>
observed_atstring<date-time>required
episode_keystringrequired
labelstringrequired
detailstringrequired
recovery_actionsArray<object>required
Show child attributes
typestringconnect_domaincontact_supportrequired
labelstringrequired
urlstring<uri>required
initial_bulk_observationobject
Show child attributes
statusstringobservingdeferredrequired
reason_codestringrequired
retry_atstring<date-time>required
labelstringrequired
detailstringrequired
Show child attributes
typestringrequired
keystring
statusstringreadydeferredrequired
next_dispatch_atstring<date-time>
minimum_interval_secondsnumber>= 0required
baseline_rate_per_secondnumber>= 0
effective_rate_per_secondnumber>= 0
cooldown_reasonstring
cooldown_untilstring<date-time>
feedback_epochinteger>= 0required

SharedSenderStatus

object
statusstringreadydeferredpauseddegradedrequired
reason_codestringshared_sender_rate_limitedshared_sender_provider_backpressureshared_sender_evidence_pending
retry_atstring<date-time>
observed_atstring<date-time>required
episode_keystringrequired
labelstringrequired
detailstringrequired
recovery_actionsArray<object>required
Show child attributes
typestringconnect_domaincontact_supportrequired
labelstringrequired
urlstring<uri>required

DeliveryStatusIssue

object
controlstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacityrequired
reason_codestringsending_pausedbrand_unavailablesender_not_readysending_capacity_reachedsignup_sending_capacity_reacheddelivery_evidence_pendingrequired
retryablebooleanrequired
retry_atstring<date-time>

DeliveryStatus

object
assessment_scopestringrequired
admission_statusstringalloweddeferreddeniedrequired
sending_pauseSendingPause

What 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.

Show child attributes
sending_pausedbooleantruerequired
reasonstringcritical_bounce_ratecritical_complaint_rate

Present only for an explained deliverability pause.

occurred_atstring<date-time>required
headlinestringrequired
detailstringrequired
what_to_doArray<string>

Present only for an explained deliverability pause.

request_reviewstringrequired

The instruction an agent relays to the owner.

recovery_actionsArray<object>required
Show child attributes
typestringverify_listrequest_reviewcontact_supportrequired
labelstringrequired
urlstringrequired

App link or support mailto.

commercial_capacityDeliveryCapacityrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
shared_abuse_capacitySharedAbuseCapacityrequired

Retired shared probation allowance. Status is always not_applicable; the field remains for compatibility.

Show child attributes
statusstringavailabledeferrednot_applicableunknowndegradedrequired
reason_codestring
retry_atstring<date-time>
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
pacing_stateDeliveryPacingStaterequired
Show child attributes
statusstringreadydeferredrequired
policy_versionstringrequired
queued_quantityinteger>= 0
next_dispatch_atstring<date-time>
shared_senderSharedSenderStatus
Show child attributes
statusstringreadydeferredpauseddegradedrequired
reason_codestringshared_sender_rate_limitedshared_sender_provider_backpressureshared_sender_evidence_pending
retry_atstring<date-time>
observed_atstring<date-time>required
episode_keystringrequired
labelstringrequired
detailstringrequired
recovery_actionsArray<object>required
Show child attributes
typestringconnect_domaincontact_supportrequired
labelstringrequired
urlstring<uri>required
initial_bulk_observationobject
Show child attributes
statusstringobservingdeferredrequired
reason_codestringrequired
retry_atstring<date-time>required
labelstringrequired
detailstringrequired
Show child attributes
typestringrequired
keystring
statusstringreadydeferredrequired
next_dispatch_atstring<date-time>
minimum_interval_secondsnumber>= 0required
baseline_rate_per_secondnumber>= 0
effective_rate_per_secondnumber>= 0
cooldown_reasonstring
cooldown_untilstring<date-time>
feedback_epochinteger>= 0required
blocking_controlstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacity
reason_codestring
Show child attributes
controlstringaccount_statusbrandsender_identitycommercial_capacityshared_abuse_capacityrequired
reason_codestringsending_pausedbrand_unavailablesender_not_readysending_capacity_reachedsignup_sending_capacity_reacheddelivery_evidence_pendingrequired
retryablebooleanrequired
retry_atstring<date-time>
retry_atstring<date-time>
observed_atstring<date-time>required

CampaignVersionInput

object
subjectstringrequired
generation_event_idinteger

From a suggested line in readiness versions.lines.

candidate_locatorstring

From a suggested line in readiness versions.lines.

CampaignWinnerInput

object

Send 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.

test_share_percentinteger[1, 95]required

From readiness versions.test_shares[n].min_bp / 100 up to 95.

wait_hoursinteger248244
measurestringopensclicksopens

SubjectVersionOffer

object

Subject line versions for this campaign's audience. Read only.

eligibleboolean
audience_countinteger | null
max_versionsinteger
test_sharesobject | null

By number of lines kept (2 up to max_versions): the smallest and the starting winner test share in basis points, and whether sending the winner fits. Null while the audience count is unknown.

Show child attributes
[key: string]object
Show child attributes
min_bpinteger
default_bpinteger
winner_availableboolean
wait_hoursArray<integer>
statusstringnonewritingreadyunavailable
phasestringchecking

While writing: the lines are written and their checks have begun. Absent before that.

reasonstring
linesArray<object>

Suggested alternatives for the current content.

Show child attributes
subjectstring
approachstring
generation_event_idinteger
candidate_locatorstring

CampaignExperiment

object

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null

DeliveryReviewBudgetStatus

object

Read-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_applicableunavailablerequired
assessment_scopestringrequired
channelstringrequired
observed_atstring<date-time>required
messagestringrequired
notestringrequired
reason_codestring
retry_atstring<date-time>

UTC release of the blocking calendar allowance; present when exhausted.

remainingobject
Show child attributes
hourinteger>= 0required
dayinteger>= 0required
resets_atobject
Show child attributes
hourstring<date-time>required
daystring<date-time>required

DeliveryCapacityRecovery

object

Informational 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_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring

DeliveryCapacityRecoveryAction

object
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring

ValidationAudience

object
One of
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_idinteger
segment_idinteger
all_contactsboolean

All email channels in the current Brand, subject to the 100000-candidate operation bound.

quote_digeststring

Pass 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.

any
any
any
any
any
any

ValidationOperationCounts

object
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0

ValidationOperationPricing

object
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null

ValidationOperationFunding

object
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject

ValidationOperationQuote

object
statusstringquotedneeds_fundingrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
quote_digeststringrequired
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
mutationbooleanrequired

ValidationOperation

object
operation_idstringrequired
statusstringrequestedquotedheldexecutingpartially_committedcommittedreleasedneeds_fundingfailedrequired
source_kindstringcontact_channelcontactlistsegmentall_contactsleadrequired
item_detailobjectrequired
Show child attributes
statusstringavailablecompactedrequired
compacted_atstring<date-time>
item_countinteger>= 0
Show child attributes
candidate_countinteger>= 0required
deduplicated_countinteger>= 0required
cached_countinteger>= 0required
ineligible_countinteger>= 0required
eligible_countinteger>= 0required
pending_countinteger>= 0
executing_countinteger>= 0
billable_countinteger>= 0
not_billable_countinteger>= 0
provider_unknown_countinteger>= 0
failed_countinteger>= 0
resultsobject

Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.

Show child attributes
valid_countinteger>= 0
invalid_countinteger>= 0
disposable_countinteger>= 0
unknown_countinteger>= 0
catchall_countinteger>= 0
unconfirmedobject

Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.

Show child attributes
excluded_countinteger>= 0

Addresses this run currently holds out of sends.

sendable_countinteger>= 0

This run's unknown and catch-all addresses still in sends.

pendingboolean

The run is still leaving its unconfirmed addresses out.

kept_countinteger>= 0
kept_atstring<date-time>
can_includeboolean

Including this run's left-out addresses can be requested now.

can_leave_outboolean

Leaving this run's sendable unconfirmed addresses out can be requested now.

include_blockedboolean

Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.

Show child attributes
price_book_versionstringrequired
unit_rate_centsstringrequired
included_quantityinteger>= 0
maximum_charge_centsinteger>= 0required
committed_centsinteger>= 0
released_centsinteger>= 0
currencystringrequired
quote_digeststring
expires_atstring<date-time>required
execution_deadline_atstring<date-time> | null
Show child attributes
routestringrequired
availablebooleanrequired
reasonstring
usage_event_idinteger
statestringneeds_fundingheldcommittedreleased
recoveryobject
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>
failure_codestring
started_atstring<date-time>
completed_atstring<date-time>
next_actionstring

ValidationOperationItem

object
idintegerrequired
contact_channel_idinteger | null
lead_idinteger | null
emailstring<email>

Current address only if it still matches the retained verification identity

provider_observed_atstring<date-time> | null
statusstringpendingexecutingbillablenot_billableprovider_unknownfailedrequired
billableboolean
providerstring
native_statusstring
verdictstring
failure_codestring
result_referenceobject
completed_atstring<date-time>

ContactEnrichmentQuote

object
quote_digeststring
selected_countintegerrequired
already_current_countintegerrequired
reusable_countintegerrequired
provider_required_countintegerrequired
unavailable_countintegerrequired
maximum_billable_outcomesintegerrequired
resourcestringcontact_profile_enrichment
unit_rate_centsstringrequired
maximum_charge_centsintegerrequired
currencystringUSDrequired
price_book_versionstringrequired
availablebooleanrequired
reasonstring | null
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>

SpendProjection

object
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>

PaidActionIntentCreate

object
adapter_keystringrequired
adapter_versionstringrequired
operation_idempotency_keystringrequired
state_payloadobjectrequired

Adapter-owned state, validated and encrypted before persistence.

PaidActionIntent

object
idstringrequired

Opaque public continuation identifier.

schemastringrequired
statusstringopenawaiting_fundingready_to_resumeconsumedcancelledexpiredrequired
adapterobjectrequired
Show child attributes
keystringrequired
versionstringrequired
operation_idempotency_keystringrequired
original_quote_fingerprintstringrequired
current_quote_fingerprintstring
quote_changedboolean
state_payloadobject
quoteobject
expires_atstring<date-time>required
consumed_atstring<date-time> | null
cancelled_atstring<date-time> | null

SpendBalance

object
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required

SpendRecoveryAction

object
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>

ContactEnrichmentFundingRequired

object
codestringrequired
messagestringrequired
errorbooleanrequired
error_codestringrequired
currencystringrequired
required_centsinteger>= 0required
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired
recovery_actionobjectrequired
spendSpendProjectionrequired
Show child attributes
schemastringrequired
statusstringreadyneeds_fundingpayment_pendingblockedunavailablerequired
routestringdirect_prepaidincludedpostpaidshopifyvercellegacyrequired
currencystringrequired
maximum_charge_centsinteger>= 0required
Show child attributes
available_centsintegerrequired
reserved_centsinteger>= 0required
shortfall_centsinteger>= 0required
fundingobjectrequired

Canonical account funding projection from Billing::Funding::Presenter.

recovery_actionSpendRecoveryActionrequired
Show child attributes
typestringadd_fundsretry_add_fundscomplete_checkoutwait_for_paymentask_account_adminmanage_in_shopifymanage_in_marketplacecontact_supportunavailable
reasonstring
operationstringadd_funds
urlstring<uri>
purchase_idinteger
shortfall_centsinteger>= 0
minimum_centsinteger>= 0
maximum_centsinteger>= 0
recommended_centsinteger>= 0
preset_centsArray<integer>

ContactEnrichmentDispatch

object
selected_countintegerrequired
queued_countintegerrequired
already_current_countintegerrequired
reusable_countintegerrequired
provider_required_countintegerrequired
unavailable_countintegerrequired
maximum_charge_centsintegerrequired
currencystringUSDrequired
price_book_versionstringrequired
idempotent_replaybooleanrequired

Contact

object
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
flag_emojistring | null

Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

dataobject

Custom 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.

Example
{
  "tags": [
    "vip",
    "newsletter"
  ],
  "plan": "pro"
}
subscribed_phoneboolean
subscribed_emailboolean
emailstring<email> | null

Convenience value for the preferred email channel. Full channel detail remains in channels[].

subscribedobject

Denormalized subscription summary by channel family.

Show child attributes
emailboolean
phoneboolean
verification_statusstringverifiedsuppressedunverified
verification_resultstring | nullvalidinvaliddisposablecatchallunknownnull

Newest list-verification result for the contact's email; null when never checked.

enrichment_statusstringenrichednot_enriched
mailbox_providerstringgmailappleoutlookcorporateunknown

Derived 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> | null
created_atstring<date-time>
updated_atstring<date-time>
engagementobject | null

Aggregated 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.

Show child attributes
ratingstringengagedwarmcoolingdormantnever

Five-tier engagement rating based on recency of opens and clicks.

emails_sentinteger
unique_opensinteger
clicksinteger
open_ratenumber<float> | null
click_ratenumber<float> | null
last_opened_atstring<date-time> | null
last_clicked_atstring<date-time> | null
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>

ContactChannel

object
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>

ImageAsset

object
media_kindstringimage
media_urlstring<uri>
image_urlstring<uri>
signed_idstring
filenamestring
content_typestring
byte_sizeinteger
widthinteger | null

Intrinsic pixel width when detectable.

heightinteger | null

Intrinsic pixel height when detectable.

ContactList

object
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

ListDeleteWarning

object
campaign_namesArray<string>
flow_namesArray<string>

BulkListContactsRequest

object
actionstringaddremoverequired

Add existing contacts to the list or remove them from it.

emailsArray<string>required

BulkListContactsResponse

object
actionstringaddremove
list_idinteger
addedinteger

Contacts newly added for add actions

removedinteger

Contacts removed for remove actions

already_in_listArray<string>
not_in_listArray<string>
not_foundArray<string>
invalid_emailsArray<string>

DirectUploadCreateRequest

object
purposestringimportimagemedia_asset

Set to import for CSV contact imports, or image/media_asset for image media assets.

blobobjectrequired
Show child attributes
filenamestringrequired
Example
contacts.csv
byte_sizeintegerrequired
Example
1048576
checksumstringrequired

Base64-encoded MD5 checksum for Active Storage direct upload.

content_typestring
Example
text/csv
metadataobject

DirectUpload

object
signed_idstring

Submit this value to endpoints that consume direct uploads.

filenamestring
byte_sizeinteger
content_typestring | null
direct_uploadobject
Show child attributes
urlstring<uri>
headersobject
Show child attributes
[key: string]string

ImportPolicy

object

Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.

standingstringrequired

The account standing the limits derive from.

Example
trusted
max_rowsinteger | nullrequired

Row ceiling for one import. Null means no row ceiling for this standing.

Example
null
max_file_size_bytesintegerrequired
Example
2147483648
max_file_size_mbintegerrequired
Example
2048
max_active_importsintegerrequired
Example
10
create_rate_limit_per_minuteintegerrequired
Example
10
direct_upload_rate_limit_per_minuteintegerrequired
Example
30
write_modesArray<string>realshadowdry_runrequired

ImportSpec

object
resourcestringcontactsleadsrequired
parserstringdefaultrequired
uiobject
required_rulesobject
fieldsArray<object>required

Default 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.

guardrailsImportPolicyrequired

Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.

Show child attributes
standingstringrequired

The account standing the limits derive from.

Example
trusted
max_rowsinteger | nullrequired

Row ceiling for one import. Null means no row ceiling for this standing.

Example
null
max_file_size_bytesintegerrequired
Example
2147483648
max_file_size_mbintegerrequired
Example
2048
max_active_importsintegerrequired
Example
10
create_rate_limit_per_minuteintegerrequired
Example
10
direct_upload_rate_limit_per_minuteintegerrequired
Example
30
write_modesArray<string>realshadowdry_runrequired

ImportGuardrail

object

How this import stands against the account's standing row limit.

tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000

Import

object
idinteger
resourcestringcontactsleads
parserstringdefault
statusstringpendingprocessingfailedcanceledcompletecontact_us
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
email_rowsobject | null

Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.

Show child attributes
subscribedinteger
unsubscribedinteger
blockedinteger
warning_rowsinteger

Rows 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.

progressobject

Canonical live-progress block (the single progress representation). pct is the only percent source; a null pct means indeterminate.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null
stagesArray<object>
Show child attributes
keystring
labelstring
countinteger
statestringdoneactivependingfailed
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
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.

Show child attributes
Array<integer | string>
Show child attributes
One of
integer
string
columnsobject | null
optionsobject | null
assigned_list_idsArray<integer>
assigned_listsArray<object>
Show child attributes
idinteger
namestring

How this import stands against the account's standing row limit.

Show child attributes
tierstringautocontact_usrequired

auto when the row count is within the standing limit; contact_us when it is above it and the import halted.

statusstringokcontact_salesrequired

Client-facing guardrail status vocabulary.

standingstringrequired

The account standing the limit derives from.

Example
probation
max_rowsinteger | nullrequired

Row ceiling for the standing. Null means no row ceiling.

Example
250000
flows_not_startedobject | null

Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.

Show child attributes
flowsArray<object>required
Show child attributes
idinteger
namestring
messagestringrequired
next_stepstringrequired
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>

Export

object
idinteger
resourcestringcontactsleads
formatstringcsv
statusstringpendingprocessingcompletefailed
total_rowsinteger | null
rows_writteninteger

Rows written so far; the live numerator against total_rows.

error_messagestring | null
readyboolean

True once the export is complete and the file is available.

download_pathstring | null

Path to download the CSV; present only when ready is true.

progressobject

Live 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.

Show child attributes
statusstringpendingrunningcompletefailed
pctnumber | null

Completion percentage, or null when indeterminate.

stagesArray<object>
Show child attributes
keystring
labelstring
countinteger | null
statestringdoneactivependingfailed
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>

SavedView

object
idinteger
surfacestringcontactssendingactivity
namestring
visibilitystringprivateshared

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Table layout preset for contacts surface views. Only present when surface = contacts.

Show child attributes
columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

ownerboolean

True when the current user is the creator of this view

created_atstring<date-time>
updated_atstring<date-time>

SavedViewLayout

object

Table layout preset for contacts surface views. Only present when surface = contacts.

columnsArray<string>

Ordered list of column keys to display

sortobject
Show child attributes
fieldstring

Column key to sort by

dirstringascdesc

Sort direction

Segment

object
idinteger
account_idinteger
brand_idinteger | null
namestring
originstringusersystem

Who 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.

Request-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.

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
cached_countinteger | null

Last asynchronously refreshed contact count for this segment.

count_computed_atstring<date-time> | null

When cached_count was last refreshed.

created_atstring<date-time>
updated_atstring<date-time>

SegmentFilterExpression

object

Request-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.

One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

FlatAndSegmentFilterExpression

object
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

SegmentFilterNode

object
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<any>required

Nested filter nodes. NOT groups must contain exactly one condition.

BooleanSegmentFilterGroup

object
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

SegmentFilters

array

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

SegmentPreview

object
countinteger

Live count of contacts matching the supplied filters.

sampleArray<object>

Bounded contact sample for quick verification.

Show child attributes
idinteger
emailstring | null
namestring | null
overlapArray<object>

Bounded overlap with existing segments.

Show child attributes
segment_idinteger
namestring
overlap_countinteger

AttributeSegmentFilter

object
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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

object
One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Campaign

object
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
dashboard_urlstring<uri> | null

Canonical dashboard URL with the /my route prefix.

preview_urlstring<uri> | null

Signed, expiring public preview URL for the current template version.

recipient_snapshotobject | null

Last send snapshot. Values are captured at send time and are not a live audience estimate.

Show child attributes
requested_recipientsinteger | null
dispatched_recipientsinteger | null
blocked_recipientsinteger | null
requested_send_unitsinteger | null
dispatched_send_unitsinteger | null
units_per_recipientinteger | null
send_tokenstring | null
started_atstring<date-time> | null
completed_atstring<date-time> | null
last_send_recipientsinteger | null

Alias for the last dispatched recipient snapshot stored in data.recipients.

deliveryCampaignDeliverySummary | null

Present while a campaign has a current send token; use /delivery to poll, refresh progress, and receive polling metadata.

Show child attributes
One of
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
null
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
editablebooleanread only

True 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>
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateTemplate | null
Show child attributes
One of
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>
null
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null

CampaignDeliverySummary

object
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired

CampaignDeliveryProgress

object

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Show child attributes
idinteger
recipientsinteger
modestringsplitwinner
statestringrunningawaiting_winnersending_winnercompletestopped
measurestringopensclicks
stop_reasonstring
test_share_percentnumber
wait_hoursinteger
decide_atstring<date-time>
decided_atstring<date-time>
winner_sentinteger
versionsArray<object>
Show child attributes
keyinteger
letterstring
subjectstring
ownboolean
writerstringownerai
approachstring
sentinteger
open_ratenumber | null
click_ratenumber | null
unsubscribe_ratenumber | null

People who unsubscribed after this version was sent, by the horizon, over sent.

verdictobject
Show child attributes
rulestring
reasonstring
winner_keyinteger | null
chosen_keyinteger | null
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
stop_reasonstring | null

Why a stopped send stopped, such as email_under_review for one held by the safety check.

safety_reviewobject | null

For 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.

Show child attributes
how_to_fixstring
categorystring
agent_promptstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject

For a send it couldn't read, the images and other changes (as SendRefusalDetail details).

campaign_send_tokenstring | nullrequired
statusstringnot_startedawaiting_approvalsendingpausedcompletedfailedcancelledrequired
recipientsintegerrequired

Recipient count captured for the active send.

sentintegerrequired
failedintegerrequired
pendingintegerrequired
terminalbooleanrequired

True when clients can stop polling.

poll_after_secondsinteger | nullrequired

Suggested polling delay for active sends.

MailActionDescription

object

A 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>required

Identifies the interaction.

profilestringhttps://mailschema.org/profiles/map/0.3required
typeobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired
contractDigeststringrequired
issuedAtstring<date-time>required
expiresAtstring<date-time>required
inLanguagestringrequired
serviceobjectrequired
Show child attributes
idstring<uri>required

The service's HTTPS origin.

tenantstring<uri>
recipientstring<email>required
subjectobjectrequired
Show child attributes
idstring<uri>required
titlestringrequired
termsobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired

Opaque; a decision names it exactly.

detailsobjectrequired

Defined by the type contract's details schema.

operationsArray<object>required
Show child attributes
idstringrequired
capabilityobject
humanobjectrequired
Show child attributes
urlstring<uri>required

SendApproval

object
idintegerrequired
campaign_idintegerrequired
can_decidebooleanrequired

Whether the signed-in person may decide it, as the account owner or a direct account admin.

statestringpendingapproveddeclinedexpiredwithdrawnrequired

withdrawn 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_progresscompletedfailedcancelledrequired
contentobjectrequired
Show child attributes
subjectstringrequired
preheaderstring
htmlstringrequired

The exact email the approval sends.

bccstring

The address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.

mail_actionMailActionDescriptionrequired

The Campaign Send Approval 0.1 description of this send's exact terms.

Show child attributes
@contextstringhttps://mailschema.org/contexts/map-0.3.jsonldrequired
@typestringMailActionrequired
@idstring<uri>required

Identifies the interaction.

profilestringhttps://mailschema.org/profiles/map/0.3required
typeobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired
contractDigeststringrequired
issuedAtstring<date-time>required
expiresAtstring<date-time>required
inLanguagestringrequired
serviceobjectrequired
Show child attributes
idstring<uri>required

The service's HTTPS origin.

tenantstring<uri>
recipientstring<email>required
subjectobjectrequired
Show child attributes
idstring<uri>required
titlestringrequired
termsobjectrequired
Show child attributes
idstring<uri>required
versionstringrequired

Opaque; a decision names it exactly.

detailsobjectrequired

Defined by the type contract's details schema.

operationsArray<object>required
Show child attributes
idstringrequired
capabilityobject
humanobjectrequired
Show child attributes
urlstring<uri>required

MessageSendResult

object
idinteger
channelstringemailsms
tostring
recipientsobject

Full normalized email envelope, visible only to authorized account readers. Returned for email messages.

Show child attributes
toArray<string>
ccArray<string>
bccArray<string>
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
rfc_message_idstring | null

Actual 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 | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflowtest

campaign, flow, test, or null (transactional)

source_namestring | null

Name of source campaign or flow

status_reason_codestring | null

Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

status_reasonstring | null

Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdelivery

Broad category for status_reason.

failure_codestring | null

Stable machine-readable failure reason; present only when status is failed.

failure_reasonstring | null

Human-readable failure explanation; present only when status is failed.

failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdelivery

Broad category for failure_reason; present only when status is failed.

sent_atstring<date-time> | null
created_atstring<date-time>
ignored_fieldsArray<string>required

Top-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.

TestSendResult

object
outcomestringsentpartialpendingheldfaileddry_rundelivered

Dispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.

sentintegerrequired

Number of tests accepted by the sending provider.

pendinginteger
heldinteger

Tests awaiting content review; not sent and not automatically replayed after approval.

failedinteger
dry_runboolean
resultsArray<object>required
Show child attributes
emailstring
successboolean

The sending provider accepted this test; recipient delivery is separate.

statusstringsentdeliveredpendingheldfailed

held awaits content review and was not sent; delivered is the legacy acceptance label.

codestring
messagestring

Human-readable dispatch or provider-feedback detail.

errorstring

Why this recipient's test was not sent.

hold_idinteger

Exact content review case for this test.

plan_urlstring<uri>

Where to choose a plan. Present when code is test_send_cap_reached: a Setup mode account has used its 20 test recipients for the rolling 24 hours.

how_to_fixstring

Explicit recovery guidance; approval alone does not send a test.

agent_promptstring

The reason and fix to paste to an agent

Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

detailsobject

For a test the safety check couldn't read, each image that failed and the other changes to make.

Show child attributes
imagesArray<object>
changesArray<object>
message_idinteger
provider_idstring

Message

object
idinteger
channelstringemailsms
tostring
recipientsobject

Full normalized email envelope, visible only to authorized account readers. Returned for email messages.

Show child attributes
toArray<string>
ccArray<string>
bccArray<string>
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
rfc_message_idstring | null

Actual 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 | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflowtest

campaign, flow, test, or null (transactional)

source_namestring | null

Name of source campaign or flow

status_reason_codestring | null

Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

status_reasonstring | null

Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

status_reason_categorystring | nullcontent_reviewaccountinternalrecipientproviderrate_limitdelivery

Broad category for status_reason.

failure_codestring | null

Stable machine-readable failure reason; present only when status is failed.

failure_reasonstring | null

Human-readable failure explanation; present only when status is failed.

failure_categorystring | nullcontent_reviewaccountinternalrecipientproviderdelivery

Broad category for failure_reason; present only when status is failed.

sent_atstring<date-time> | null
created_atstring<date-time>

Suppression

object

Account suppression row with bounded source-event diagnostics.

idinteger
emailstring<email>
reasonstringhard_bouncesoft_bouncecomplaintmanualadminunsubscribeverificationmarketing_withheldunconfirmed
scopestringaccount_scopedbrand_scoped
brand_idinteger | null

Brand affected by a brand-specific stop.

activeboolean
contact_idinteger | null
source_providerstring | null
source_event_idstring | null
provider_diagnosticstring | null

Bounded diagnostic text extracted from the provider feedback event, when retained.

bounce_typestring | nullhardsoft
bounce_subtypestring | null
complaint_feedback_typestring | null
event_occurred_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

WebhookEventType

string
WebhookEventTypeemail.sentemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedemail.failedemail.receivedcampaign.completedcampaign.failedcampaign.stoppedflow.pausedsending.pausedsending.limit_approachingsending.limit_reachedimport.completedimport.faileddomain.verifieddomain.verification_lostdomain.dns_degradedwebhook.disabled

Webhook

object
idinteger
urlstring<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.disabled
enabledboolean
statusstringactivefailingdisabled

failing while deliveries fail; an endpoint failing for 3 days is turned off.

failing_sincestring<date-time> | null
secretstring

Standard Webhooks signing secret (whsec_...). Masked unless revealed.

last_deliveryobject | null
Show child attributes
idinteger
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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
updated_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>

WebhookWriteRequest

object
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.disabled
enabledboolean

WebhookDelivery

object
idinteger
event_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.disabled
statusstringpendingdeliveredfailed
attemptsinteger
last_response_statusinteger | null
last_errorstring | null
next_attempt_atstring<date-time>
Show child attributes
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.disabledrequired
timestampstring<date-time>required
dataobjectrequired
Show child attributes
message_idinteger | null

The id POST /v1/my/messages returned. Null on test events.

tostring
subjectstring | null
idempotency_keystring | null

The caller's Idempotency-Key, when one was sent.

tagsobject

The caller's delivery-option tags.

Show child attributes
[key: string]string
testboolean

Present and true on test events.

sent_atstring<date-time>

email.sent

bounceobject

email.bounced

Show child attributes
typestringhardsoft
subtypestring | null

The provider's bounce subtype, e.g. NoEmail or MailboxFull.

complaintobject

email.complained

Show child attributes
feedback_typestring | null

e.g. abuse

urlstring

email.clicked

failureobject

email.failed

Show child attributes
codestring
reasonstring
categorystring
created_atstring<date-time>
updated_atstring<date-time>

WebhookEventPayload

object
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.disabledrequired
timestampstring<date-time>required
dataobjectrequired
Show child attributes
message_idinteger | null

The id POST /v1/my/messages returned. Null on test events.

tostring
subjectstring | null
idempotency_keystring | null

The caller's Idempotency-Key, when one was sent.

tagsobject

The caller's delivery-option tags.

Show child attributes
[key: string]string
testboolean

Present and true on test events.

sent_atstring<date-time>

email.sent

bounceobject

email.bounced

Show child attributes
typestringhardsoft
subtypestring | null

The provider's bounce subtype, e.g. NoEmail or MailboxFull.

complaintobject

email.complained

Show child attributes
feedback_typestring | null

e.g. abuse

urlstring

email.clicked

failureobject

email.failed

Show child attributes
codestring
reasonstring
categorystring

WebhookReceivedEventPayload

object
typestringemail.receivedrequired
timestampstring<date-time>required

When the message arrived.

dataobjectrequired
Show child attributes
message_idinteger | null

The send this message answers, as POST /v1/my/messages returned it. Null when it answers none, and on test events.

idempotency_keystring | null

The answered send's Idempotency-Key, when the caller sent one.

tagsobject

The answered send's delivery-option tags; empty when it answers none.

Show child attributes
[key: string]string
fromstring
tostring

The inbox address it was sent to.

subjectstring | null
textstring | null

Plain-text body

htmlstring | null

HTML body

truncatedboolean

True when either body was cut to 64 KiB.

auto_submittedboolean

True for automatic replies such as out-of-office notices.

attachmentsArray<object>

Every file the message carried, in order, including files that are not available. Empty when it carried none.

Show child attributes
idinteger
filenamestring
content_typestring
sizeinteger

Bytes.

scannedboolean

True only when a virus scan found the file clean. Use downloadable to decide whether it can be fetched.

scan_statusstringpendingcleaninfectedfailednot_scanned

The file's scan verdict, as the conversations API reports it.

downloadableboolean

True when the conversations API will serve the file.

download_requires_confirmationboolean

True for a file no scan covered: fetch it with acknowledge_unscanned=true.

availability_reasonstring

Present only when downloadable is false. Why the file is unavailable: unsafe (a threat was found), too_large (over the per-file limit), message_limit (over the per-message size limit), storage_failed, storage_limit, invalid, scan_failed or scanning. Treat any other value as unavailable too.

attachments_omittedinteger>= 1

How many more files the message carried than attachments lists. Files past the per-message attachment limit (50) are not kept. Absent when every file is listed.

conversation_idinteger | null

For GET /v1/my/conversations/{id}. Null on test events.

conversation_message_idinteger | null

Null on test events.

testboolean

Present and true on test events.

CampaignCompletedWebhookData

object
campaign_idintegerrequired
campaign_namestring | nullrequired
campaign_send_idinteger | nullrequired
recipientsinteger | nullrequired

Recipients the send planned.

completed_atstring<date-time> | nullrequired

CampaignFailedWebhookData

object
campaign_idintegerrequired
campaign_namestring | nullrequired
campaign_send_idinteger | nullrequired
requested_recipientsinteger | nullrequired
sent_countinteger | nullrequired
failure_reasonstringrequired

A public reason code, e.g. campaign_delivery_failed.

next_actionstringrequired

What to do before sending again.

CampaignStoppedWebhookData

object
campaign_idintegerrequired
campaign_namestring | nullrequired
metricstring | nullrequired

Bounce rate or Complaint rate.

ratenumber | nullrequired

The measured rate in percent.

thresholdnumber | nullrequired

The stop threshold in percent.

total_sendsinteger | nullrequired
hard_bouncesinteger | nullrequired
complaintsinteger | nullrequired
next_actionstring | nullrequired

FlowPausedWebhookData

object
flow_idintegerrequired
flow_namestring | nullrequired
metricstring | nullrequired

Bounce rate or Complaint rate.

ratenumber | nullrequired

The measured rate in percent.

thresholdnumber | nullrequired

The pause threshold in percent.

SendingPausedWebhookData

object
reasonstring | nullrequired

Why, e.g. critical_bounce_rate. Null when the pause is not explained.

sending_pausedbooleanrequired
occurred_atstring<date-time> | nullrequired

SendingLimitWebhookData

object
statestringapproachingreachedrequired
labelstringrequired
detailstringrequired
usage_percentintegerrequired

Share of the allowance used.

capacityobjectrequired
Show child attributes
limitintegerrequired

Sends allowed per window.

remainingintegerrequired
window_secondsintegerrequired

The rolling window

retry_atstring<date-time> | nullrequired

When capacity frees up

upgrade_urlstring | nullrequired

Where an owner on the free plan can upgrade.

ImportCompletedWebhookData

object
resourcestring | nullcontactsleadsnullrequired
import_idintegerrequired
list_namestring | nullrequired
success_rowsinteger | nullrequired
failed_rowsinteger | nullrequired
total_rowsinteger | nullrequired

ImportFailedWebhookData

object
import_idinteger | nullrequired
reasonstring | nullrequired
failed_rowsinteger | nullrequired

DomainVerifiedWebhookData

object
domain_idintegerrequired
domainstringrequired

DomainVerificationLostWebhookData

object
domain_idintegerrequired
domainstringrequired
failingArray<string>required

The DNS record families that failed, e.g. dkim.

DomainDnsDegradedWebhookData

object
domain_idinteger | nullrequired
domainstringrequired
failingArray<string>required

The DNS record families that failed, e.g. dkim.

classificationstring | nullrequired
actionstring | nullrequired

WebhookDisabledWebhookData

object
webhook_idintegerrequired
urlstringrequired

The endpoint URL without credentials or query.

failing_sincestring<date-time> | nullrequired

ChatMessage

object
idinteger
rolestringuserassistanttoolsystem
contentstring

Credential-shaped values are redacted before display.

tool_callsArray<object>
Show child attributes
idstring
namestring
inputobject
safeboolean
statusstringpendingapprovedexecutingcompletedrejectederrorcancelleduncertain
approval_tokenstring

Binds a proposal to its execution and exact arguments. Commands also require the originating authenticated user.

resultany

Recorded tool outcome; queued does not mean sent.

actionsArray<object>
attachmentsArray<object>

Images the person added to the message, from the brand's image library.

Show child attributes
urlstring<uri>

The image's library URL.

filenamestring
content_typestringimage/pngimage/jpegimage/webp
widthinteger | null
heightinteger | null
sequenceinteger
created_atstring<date-time>

ChatSession

object
idinteger
account_idinteger
brand_idinteger
titlestring
statusstringactiveclosedfailed
started_atstring<date-time>
last_message_atstring<date-time>
message_countinteger
created_atstring<date-time>
updated_atstring<date-time>

ChatSessionDetail

object
idinteger
account_idinteger
brand_idinteger
titlestring
statusstringactiveclosedfailed
started_atstring<date-time>
last_message_atstring<date-time>
message_countinteger
created_atstring<date-time>
updated_atstring<date-time>
Show child attributes
idinteger
rolestringuserassistanttoolsystem
contentstring

Credential-shaped values are redacted before display.

tool_callsArray<object>
Show child attributes
idstring
namestring
inputobject
safeboolean
statusstringpendingapprovedexecutingcompletedrejectederrorcancelleduncertain
approval_tokenstring

Binds a proposal to its execution and exact arguments. Commands also require the originating authenticated user.

resultany

Recorded tool outcome; queued does not mean sent.

actionsArray<object>
attachmentsArray<object>

Images the person added to the message, from the brand's image library.

Show child attributes
urlstring<uri>

The image's library URL.

filenamestring
content_typestringimage/pngimage/jpegimage/webp
widthinteger | null
heightinteger | null
sequenceinteger
created_atstring<date-time>

EmailContentFormat

string

Durable 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.

EmailContentFormatdesignedplain

Template

object
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

GenerationProvenance

object

Candidate-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.

statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited

EmailLibraryTemplate

object
idstring
namestring
categorystring
tagsArray<string>
descriptionstring
subjectstring

Suggested subject line

preheaderstring

Suggested preheader

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
preview_htmlstring | null
branded_designEmailDesign

Same layout with palette overrides stripped so brand colors apply

Show child attributes

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
branded_preview_htmlstring | null

PublicEmailCatalogTemplate

object
idstringrequired
revisionstring

Digest of the concrete public design.

collectionstringbrand_studies

Present for a brand concept study; originals retain their existing response shape.

studyobject
Show child attributes
brandstringrequired
conceptbooleantruerequired
adaptedboolean
source_urlstring<uri>required
namestringrequired
categorystringrequired
tagsArray<string>required
descriptionstringrequired
subjectstringrequired
preheaderstringrequired
designEmailDesignrequired

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring

GuestFlowDemo

object

One 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.

statusstringscanninggeneratingreadyfailedexpiredrequired
revisioninteger

Advances with each brand edit or generation retry. Absent when expired.

domainstring
goalstring
brandobject

Scanned Brand Kit fields, present once the scan has completed.

logo_urlstring

Scanned logo

flowobject

The generated draft for the current revision, present when ready.

failed_stagestringscangenerate

Present when failed. A failed scan cannot be retried; start again.

messagestring

Visitor copy, present when failed or expired.

error_codestringflow_demo_attempts_exhausted

Present when a generation failed on the demo's last attempt: it cannot be retried, and message offers an account instead.

TemplateSummary

object
idinteger
namestring | null
versioninteger
content_formatEmailContentFormatdesignedplain

Durable 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 | null

Rendered preview, present only with ?include_previews=1

subjectstring | null
preheaderstring | null
flow_idinteger | null
section_countinteger
section_typesArray<string>
created_atstring<date-time>
updated_atstring<date-time>

Flow

object
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftlivepausedarchivedcancelled
approval_statestring
namestring
goalstring | null

Trigger as returned by Flow::Format.dump

Show child attributes
stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null
Show child attributes

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean
reply_readinessobject | null

Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.

Show child attributes
readybooleanrequired
messagestringrequired
retry_atstring<date-time> | null
resume_planFlowResumePlan
Show child attributes
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired
routesArray<object>required
Show child attributes
action_namestring
addressstring | null
statestring
messagestring
inbox_idinteger
sending_identity_idinteger
retry_atstring<date-time>
sent_countinteger
Show child attributes
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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.

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

Show child attributes
attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null
draft_revision_idinteger | null
draft_revision_digeststring | null
draft_approval_statestring | nullpending_reviewapprovedrejected
active_revision_idinteger | null
active_revision_digeststring | null
has_unpublished_changesboolean
unpublished_changeobject | null

Null 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.

Show child attributes
revision_idintegerrequired
saved_atstring<date-time>required
blockersArray<object>
Show child attributes
checkstringrequired
messagestringrequired
how_to_fixstring
Show child attributes
typestringask_teamdomain_settingsrequired
labelstringrequired
urlstringrequired

For ask_team, opens the app in the right account with a request to the team staged in NitroLLM; it is never sent automatically.

review_idinteger

The held case

promptstring

The staged request

agent_promptstring

Each held email's fix to paste to an agent, joined.

disclosuresArray<object>

Each held flow email and its case.

Show child attributes
actionstring
review_idinteger
categorystring
agent_promptstring
saves_publishboolean

True 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>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
versioninteger
subjectstring | null
bodystring | null
content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
block_usageobject

Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.

Show child attributes
emailsinteger

Emails linking it.

publishesinteger

Emails in live or paused flows that publish the edit.

draftsinteger

Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published

unchangedinteger

Emails that keep their content (campaigns no longer unapproved drafts

preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designEmailDesign | null
Show child attributes
One of

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
null
variablesobject
generation_provenanceGenerationProvenance

Candidate-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.

Show child attributes
statestringcandidateacceptedrequired
event_idintegerrequired
candidate_locatorstring
generated_slice_digeststring
acceptance_idinteger
saved_authored_digeststring
edit_relationstringidenticaledited
created_atstring<date-time>
updated_atstring<date-time>

FlowResumePlan

object
flow_idintegerrequired
statusstringdraftlivepausedarchivedcancelledrequired
open_journey_countinteger>= 0required
contact_countinteger>= 0required
waiting_journey_countinteger>= 0required
scheduled_journey_countinteger>= 0required
has_unpublished_changesbooleanrequired
draft_approval_statestring | nullpending_reviewapprovedrejected
requires_choicebooleanrequired
allowed_modesArray<string>new_contacts_onlycontinue_existingrequired
recommended_modestringnew_contacts_onlyrequired

FlowTemplate

object

Lean flow template card for index listings.

idstring

Template slug (e.g. welcome)

type_labelstring
descriptionstring
categorystring
iconstring

Font Awesome icon name for the template's card, without the fa- prefix.

needs_listboolean

Whether creating it takes trigger.contact_list_id, the brand list it starts on.

brand_writableboolean

Whether POST /v1/my/flows/generate can write this template for the brand.

email_countinteger
step_countinteger

FlowTemplateDetail

object

Lean flow template card for index listings.

idstring

Template slug (e.g. welcome)

type_labelstring
descriptionstring
categorystring
iconstring

Font Awesome icon name for the template's card, without the fa- prefix.

needs_listboolean

Whether creating it takes trigger.contact_list_id, the brand list it starts on.

brand_writableboolean

Whether POST /v1/my/flows/generate can write this template for the brand.

email_countinteger
step_countinteger

Full flow template including the graph, ready for POST /v1/my/flows.

triggerobject

Trigger 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

object

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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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

object
accountEngagementBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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 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.

sentintegerrequired

Emails the provider accepted in this bucket (test sends excluded).

deliveredintegerrequired

Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

non_bouncedinteger

Accepted emails minus known bounces; the denominator of open and click rates.

unconfirmedinteger

Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

opensintegerrequired

Non-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_opensintegerrequired

All counted open observations of non-bounced emails, including repeat opens, so total_opens >= opens. A volume figure, never a rate numerator.

open_ratenumber<float> | nullrequired

opens / 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

object

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.

sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

MessageSendsEngagement

object
intervalstringhourdaymonthrequired

Series bucket size (hour for today, month for all time, otherwise day).

summaryEngagementCohortBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

seriesArray<object & EngagementCohortBucket>required

One entry per interval of the window (zero-filled), plus any later interval with sends; entries add up to summary.

Show child attributes
bucket_startstring<date-time>required

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.

sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

has_sendsbooleanrequired

Whether the source has ever accepted a non-test email (outside the window too).

MessageSendsRow

object
source_typestringcampaignflowtransactionaltestrequired
row_keystringrequired
source_idinteger | null

Campaign or flow id; null for transactional and test rows.

source_namestringrequired
datestring<date> | null

Creation day of a transactional or test row.

subjectstring | null
recipientsstring | null
recipients_countinteger
totalintegerrequired

Messages in the row (every status and channel) within the window.

sentintegerrequired

Messages of the row the provider accepted (every channel).

failedintegerrequired
queuedintegerrequired
latest_failure_codestring | null
latest_failure_reasonstring | null
latest_failure_categorystring | null
last_sent_atstring<date-time> | null
deliveredintegerrequired

The row's provider-confirmed deliveries (0 on test and failed-only rows).

non_bouncedinteger

Accepted non-test emails minus known bounces.

unconfirmedinteger

Accepted non-test emails without a final provider outcome.

openedintegerrequired

Non-bounced emails of the row opened at least once; privacy image loads can count.

clickedintegerrequired

Non-bounced emails of the row clicked at least once.

open_ratenumberrequired

Percentage (0-100, 1 dp) of non_bounced; 0 without a denominator.

click_ratenumberrequired

Percentage (0-100, 1 dp) of non_bounced; 0 without a denominator.

deliveryobject

Send progress of a campaign row with an active send (same projection as the campaign delivery endpoints).

MessageSendsCounts

object

Message counts for the filter pills, over the same window as the rows.

allintegerrequired

Messages of every source in the since window (with failed).

campaignintegerrequired
flowintegerrequired
transactionalintegerrequired
testintegerrequired
timeobjectrequired

Messages of the selected source (with failed) per window.

Show child attributes
allintegerrequired
todayintegerrequired
7dintegerrequired
30dintegerrequired
3mintegerrequired

MessageSendsResponse

object
Show child attributes
source_typestringcampaignflowtransactionaltestrequired
row_keystringrequired
source_idinteger | null

Campaign or flow id; null for transactional and test rows.

source_namestringrequired
datestring<date> | null

Creation day of a transactional or test row.

subjectstring | null
recipientsstring | null
recipients_countinteger
totalintegerrequired

Messages in the row (every status and channel) within the window.

sentintegerrequired

Messages of the row the provider accepted (every channel).

failedintegerrequired
queuedintegerrequired
latest_failure_codestring | null
latest_failure_reasonstring | null
latest_failure_categorystring | null
last_sent_atstring<date-time> | null
deliveredintegerrequired

The row's provider-confirmed deliveries (0 on test and failed-only rows).

non_bouncedinteger

Accepted non-test emails minus known bounces.

unconfirmedinteger

Accepted non-test emails without a final provider outcome.

openedintegerrequired

Non-bounced emails of the row opened at least once; privacy image loads can count.

clickedintegerrequired

Non-bounced emails of the row clicked at least once.

open_ratenumberrequired

Percentage (0-100, 1 dp) of non_bounced; 0 without a denominator.

click_ratenumberrequired

Percentage (0-100, 1 dp) of non_bounced; 0 without a denominator.

deliveryobject

Send progress of a campaign row with an active send (same projection as the campaign delivery endpoints).

countsMessageSendsCountsrequired

Message counts for the filter pills, over the same window as the rows.

Show child attributes
allintegerrequired

Messages of every source in the since window (with failed).

campaignintegerrequired
flowintegerrequired
transactionalintegerrequired
testintegerrequired
timeobjectrequired

Messages of the selected source (with failed) per window.

Show child attributes
allintegerrequired
todayintegerrequired
7dintegerrequired
30dintegerrequired
3mintegerrequired
engagementMessageSendsEngagementrequired
Show child attributes
intervalstringhourdaymonthrequired

Series bucket size (hour for today, month for all time, otherwise day).

summaryEngagementCohortBucketrequired

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.

Show child attributes
sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

seriesArray<object & EngagementCohortBucket>required

One entry per interval of the window (zero-filled), plus any later interval with sends; entries add up to summary.

Show child attributes
bucket_startstring<date-time>required

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.

sentintegerrequired

Emails the provider accepted.

deliveredintegerrequired

Provider-confirmed deliveries excluding final bounces.

non_bouncedinteger

sent - bounced; the open and click rate denominator.

unconfirmedinteger

sent - bounced - delivered; missing feedback is neither a confirmed delivery nor a bounce.

bouncedintegerrequired

Emails that bounced.

opensintegerrequired

Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

total_opensintegerrequired

Counted open observations including repeats; never a rate numerator.

clicksintegerrequired

Non-bounced emails clicked at least once; clicks <= non_bounced.

total_clicksintegerrequired

Counted click observations of non-bounced emails.

forwardsintegerrequired

Non-bounced emails with a recorded forward.

delivered_ratenumber<float> | nullrequired

delivered / sent.

open_ratenumber<float> | nullrequired

opens / non_bounced.

click_ratenumber<float> | nullrequired

clicks / non_bounced.

bounce_ratenumber<float> | nullrequired

bounced / sent.

has_sendsbooleanrequired

Whether the source has ever accepted a non-test email (outside the window too).

RevenueMessageBreakdown

object
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null

RevenueReport

object

Attributed revenue from the orders ledger. This block is omitted when the brand has no connected Shopify or Stripe revenue source.

attribution_labelstring
Example
Attributed revenue. Last click, 7-day window.
currencystring | null

Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

deliveredinteger
attributed_ordersinteger
revenue_per_recipientnumber<float> | null

Net attributed revenue in major currency units divided by delivered recipients.

conversion_ratenumber<float> | null

Attributed paid orders divided by delivered recipients.

attributed_aovnumber<float> | null

Net attributed revenue in major currency units divided by attributed paid orders.

Show child attributes
message_idinteger
subjectstring | null
sent_atstring<date-time> | null
currencystring | null

Dominant attributed order currency for this message row.

mixed_currencyboolean

True when attributed orders included more than one currency before dominant-currency filtering.

deliveredinteger
attributed_ordersinteger
attributed_revenue_centsinteger

Net attributed revenue in cents from the orders ledger.

revenue_per_recipientnumber<float> | null
conversion_ratenumber<float> | null
attributed_aovnumber<float> | null

ProfileEnrichmentAudience

object

Exactly one same-Brand selection. Existing identity and profile ownership are preserved.

One of
contact_idsArray<integer>
any

FlowTrigger

object
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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 | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>

FlowTriggerInput

object
stop_on_replybooleanfalse

Stop only the enrollment whose tracked email received a proven human reply. Requires monitored receiving.

reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>

New same-brand/contact events after journey entry stop future steps. Pinned in the approved revision; cannot recall a step already executing.

eventstring

Built-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_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — 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

dataobject

FlowTriggerOutput

object

Trigger as returned by Flow::Format.dump

stop_on_replyboolean
reply_sourceobject
Show child attributes
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

exit_eventsArray<string>
eventstring
segment_idinteger | null
contact_list_idinteger | null
exclude_segment_idsArray<integer>

Segment IDs whose matching contacts are excluded from the recipient set

dataobject | null

FlowStepInput

object
typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscriberequired
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject

Every declared category key and other must have an explicit path. A branch node ends its sequence.

Show child attributes
reply_allbooleanfalse
ccArray<string>
bccArray<string>
subjectstring

Email step: subject line

bodystring

SMS body or email plain text

content_formatEmailContentFormatdesignedplain

Durable 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_modestringderivedcustom
preheaderstring

Email step: preheader

from_namestring
from_emailstring
reply_tostring

Email template design document

Show child attributes
versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring
durationinteger>= 0

Wait step: seconds, positive unless send_at is configured

send_atstring

First 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_zonestring

IANA time zone for send_at. Defaults from the account owner or Etc/UTC and is pinned in the approved runtime.

Split step: condition filters

Show child attributes
One of

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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
operatorstringandrequired
notbooleanfalsefalse

Legacy 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.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired
opstringandornotrequired
conditionsArray<SegmentFilterNode>required

Nested filter nodes. NOT groups must contain exactly one condition.

Show child attributes
One of
namestringrequired

Filter 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_, with dots replaced by underscores (for example, data.attio.lifecycle_stage becomes contact_data_attio_lifecycle_stage).

predicatestringrequired

Ransack 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.

valueanyrequired

Filter 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.

One of
typestringeventrequired
eventstringrequired

Custom or known event name, e.g. first_send, project_created, checkout.

predicatestringperformednot_performedcount_at_leastcount_at_mostrequired
valueinteger>= 1

Required for count_at_least and count_at_most.

within_daysinteger>= 1

Optional rolling event recency window.

sincestring<date-time>

Optional absolute event recency cutoff.

predicatestringperformednot_performedrequired
predicatestringcount_at_leastcount_at_mostrequired

Split step: yes branch

Split step: no branch

event_namestring

Emit event step: event to fire

forward_event_databooleanfalse
event_dataobject
transactionalbooleanfalse

FlowStepOutput

object

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitclassify_replyreplyemit_eventwebhooksubscribeunsubscribe
Show child attributes
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired
branchesobject
Show child attributes
reply_allboolean
ccArray<string>
bccArray<string>
subjectstring
bodystring
content_formatEmailContentFormatdesignedplain

Persisted presentation for an email step; defaults to designed.

preheaderstring
durationinteger
send_atstring
time_zonestring
filtersArray<object>
event_namestring
forward_event_databoolean

ReplySource

object
One of
typestringanyrequired
typestringflowcampaignmessagerequired
idinteger>= 1required

Existing resource in the same brand.

ReplyCategory

object
keystringrequired

Stable branch key; other is reserved.

labelstringrequired
descriptionstringrequired

Event

object
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>

SharedSubdomain

object
idintegerrequired
namestringrequired

The recipient's visible From domain.

sending_domain_idintegerrequired
sending_domain_namestringrequired
account_idintegerrequired
account_namestringrequired
brand_idintegerrequired
brand_sidstringrequired
brand_namestringrequired
activebooleanrequired

Domain permission is current; DNS verification remains a separate requirement.

revoked_atstring<date-time> | null
dns_verifiedbooleanrequired

SubdomainSharingSummary

object
parentobjectrequired
Show child attributes
idinteger
namestring
destinationsArray<object>required
Show child attributes
account_idinteger
account_namestring
brand_idinteger
brand_sidstring
brand_namestring
destinations_truncatedbooleanrequired
subdomainsArray<SharedSubdomain>required
Show child attributes
idintegerrequired
namestringrequired

The recipient's visible From domain.

sending_domain_idintegerrequired
sending_domain_namestringrequired
account_idintegerrequired
account_namestringrequired
brand_idintegerrequired
brand_sidstringrequired
brand_namestringrequired
activebooleanrequired

Domain permission is current; DNS verification remains a separate requirement.

revoked_atstring<date-time> | null
dns_verifiedbooleanrequired
paginationobjectrequired
Show child attributes
pageinteger
total_pagesinteger
total_countinteger

Domain

object
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>

EntriSessionResponse

object
domainDomainrequired
Show child attributes
idinteger
brand_idinteger | null
namestring
providerstringses
default_from_domainstring

Domain Nitrosend will use for visible From addresses when this sending domain is selected.

subdomain_sharing_availableboolean

The current principal can manage sharing on this verified apex.

shared_subdomainobject

Present only for a shared child, including after permission ends. DNS status is independent.

Show child attributes
activeboolean
parent_domainstring | null
messagestring | null
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_mismatch

Machine-readable reason the default visible From domain is or is not authorized.

outstandingobject | null

What 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.

Show child attributes
codestringdns_recordsprovider_confirmationdomain_reviewdomain_permissionrequired

dns_records: DNS records still need adding or fixing. provider_confirmation: DNS is in place and the email provider has not confirmed the domain yet. domain_review: a Nitrosend review holds the domain. domain_permission: the subdomain no longer has its owner's permission to send or receive.

action_requiredbooleanrequired

True when the customer has to act; false when the domain verifies on its own.

itemsArray<object>required

The DNS records or provider checks still outstanding, per domain.

Show child attributes
domainstringrequired

The sending domain or its From domain.

checkstringrequired

A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).

messagestringrequired

Customer-facing explanation

next_check_atstring<date-time> | nullrequired

When Nitrosend next checks this domain automatically; null when nothing is scheduled.

integration_idinteger | null
statusstringpendingverified
dmarc_policystringnonequarantinereject

Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.

dmarc_observed_policystring | nullnonequarantinereject

Last live DMARC policy observed by Nitrosend.

Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
inbound_setupDomainInboundSetup | null
Show child attributes
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
entriobjectrequired
Show child attributes
application_idstringrequired
tokenstringrequired
prefilled_domainstringrequired
user_idstringrequired
dns_recordsArray<EntriDnsRecord>required
Show child attributes
typestring
hoststring
valuestring
ttlinteger
priorityinteger | null
manual_dns_recordsDomainDnsRecordsrequired
Show child attributes
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired

EntriSessionRequest

object
apex_mx_overridebooleanfalse

Explicitly include the prepared company-inbox MX cutover in this session.

apex_mx_confirmationstring

Exact apex domain name being approved. Required when apex_mx_override is true.

EntriSessionValidationError

object
capacity_recoveryDeliveryCapacityRecovery

Informational 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.

Show child attributes
statestringapproachingreachedcampaign_exceeds_remainingrequired
reason_codestringsending_capacity_warningsending_capacity_reachedsignup_sending_capacity_reachedrequired
blocking_controlstringcommercial_capacityshared_abuse_capacityrequired
usage_percentinteger[0, 100]
requested_quantityinteger>= 0
labelstringrequired
detailstringrequired
Show child attributes
sourcestringplanoperator_override
window_secondsinteger
statusstringknownunlimitednot_applicableunknowndegradedrequired
limitinteger | null>= 0required
reservedinteger | null>= 0required
acceptedinteger | null>= 0required
provider_unknowninteger | null>= 0required
remaininginteger | null>= 0required
upgrade_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.

Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
Show child attributes
typestringupgrade_planverify_listcontact_ownermanage_provider_billingcontact_supportrequired
labelstringrequired
detailstring
urlstring<uri>required
required_rolestring
recovery_actionobject

Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

provisioning_idinteger | null

Existing provisioning row involved in a managed-account conflict.

retryableboolean

Whether 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

object
sending_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired
receiving_dns_recordsArray<DomainDnsRecord>
Show child attributes
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired

DomainDnsRecord

object
record_typestring
namestring
relative_namestring

Record name relative to the registrable domain, as most registrars' Host field expects; @ for the apex.

valuestring
prioritystring | null
validstring | null
purposestring | null
requiredboolean | null
mail_forwardingDomainMailForwarding | null
Show child attributes
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired

DomainMailForwarding

object
enabledbooleanrequired
route_typestringlegacy_forward_allunmatched_forwardrequired
destination_typestringlegacy_mxsmtp_relayrequired
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestringrequired

DomainInboundSetupRequest

object
inbound_setupobjectrequired
Show child attributes
methodstringprovider_forwardingmxrequired
providerstringgoogle_workspacemicrosoft_365zohoother

Required when method is provider_forwarding.

local_partstring

Select an exact existing address, or request creation subject to the current inbox allowance.

inbox_idinteger

Existing inbox on this domain. Required for an ambiguous setup when local_part is omitted.

display_namestring | null
preparebooleanfalse

Prepare apex receiving before opening the existing Entri MX connection. Does not change DNS.

no_existing_mail_servicebooleanfalse

Explicit first-mailbox choice. Rejected when public MX or a saved route identifies an existing mail service.

DomainInboundSetup

object
methodstringnoneprovider_forwardingmxrequired
statusstringnot_configuredpendingactiveattentionrequired
requires_inbox_selectionboolean

Several inboxes exist and no specific inbox was selected.

mx_scopestring | nullapexsubdomain
inboxDomainInboundInbox | null
Show child attributes
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired
provider_forwardingDomainProviderForwarding | null
Show child attributes
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null
apex_mxDomainApexMxSetup | null
Show child attributes
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null

DomainInboundInbox

object
idintegerrequired
addressstring<email>required
display_namestring | null
statusstringactivedisabledarchivedrequired

DomainProviderForwarding

object
providerstringgoogle_workspacemicrosoft_365zohootherrequired
forwarding_addressstring<email>requiredread only
probe_sent_atstring<date-time> | null
verified_atstring<date-time> | null

DomainApexMxSetup

object
modestringstandaloneforward_all
preparationobject
Show child attributes
statestringqueuedpreparingprobingreadyfailed
messagestring
failure_codestring
preparedbooleanrequired
configuredbooleanrequired
approval_requiredbooleanrequired
approval_expires_atstring<date-time> | null
legacy_provider_labelstring | null
legacy_mx_recordsArray<MxRecord>required
Show child attributes
hoststringrequired
preferenceintegerrequired
setup_notestring | null

MxRecord

object
hoststringrequired
preferenceintegerrequired

EntriDnsRecord

object
typestring
hoststring
valuestring
ttlinteger
priorityinteger | null

Integration

object
idinteger
providerstringmailgunsespostmarkresendsendgridgmailmicrosoft365smtptwilioattiohubspotmailchimpactivecampaignstripeshopifyapollo
categorystringemailsmscrmrevenueecommercedata
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
Show child attributes
mailbox_addressstring<email>

Exact address authorized by a connected mailbox.

account_typestringworkspacepersonal

Google mailbox type when available.

verification_pendingboolean

SMTP address verification code is outstanding.

smtp_hoststring
smtp_portinteger
imap_hoststring
imap_portinteger
imap_usernamestring
sent_folderstring
junk_folderstring
sending_domain_idinteger | null
sending_identity_idinteger
sender_readyboolean
selected_senderboolean
connect_urlstring<uri>

Dashboard connection and reconnect action.

last_synced_atstring<date-time> | null

Mailboxes: last completed provider page of mailbox acceptance and correlated reply ingestion, not proof of delivery. Contact-sync integrations: when the last sync run completed.

api_hoststring

ActiveCampaign: the account's API host, from the API URL it was connected with.

contacts_reconciled_atstring<date-time>

ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.

list_mapping_countinteger

Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.

event_capabilitiesobject

Supported evidence only. Request acceptance is not delivery proof.

Show child attributes
acceptanceboolean
repliesboolean
deliveryboolean
complaintsboolean
secret_hintsobject
Show child attributes
[key: string]string | null
created_atstring<date-time>
updated_atstring<date-time>

SmtpFeedbackPayload

object
One of
typestringtestrequired
typestringdeliveredbouncedcomplainedrequired
message_idstringrequired

Original RFC Message-ID, with or without surrounding angle brackets.

recipientstring<email>required
occurred_atstring<date-time>required

Outcome time, no more than five minutes in the future.

statusstring

Required 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_tokenstring

Original X-Nitro-Dispatch header, supplied together with nitrosend_message_id.

any

SmtpFeedbackSetup

object
urlstring<uri>required
signing_secretstringrequired

Connection-specific whsec_ key; never included in integration lists or broadcasts.

signing_formatstringstandard_webhooksrequired
eventsArray<object>required
Show child attributes
idstring
typestringtestdeliveredbouncedcomplained
statusstringpendingprocessingprocessedignoredfailed
received_atstring<date-time>
processed_atstring<date-time> | null
message_idstring | null
recipientstring | null
error_messagestring | null

ShopifyMerchantCredentialRequest

object
shopifyobjectrequired
Show child attributes
shopstringrequired

Permanent myshopify.com domain or shop slug.

client_idstringrequiredwrite only

Client ID for the merchant-owned Shopify app.

client_secretstring<password>requiredwrite only

Client secret for the merchant-owned Shopify app.

IntegrationWriteRequest

object
integrationMailgunIntegrationInput | SesIntegrationInput | PostmarkIntegrationInput | ResendIntegrationInput | SendgridIntegrationInput | ActiveCampaignIntegrationInputrequired
Show child attributes
One of
providerstringmailgunrequired
api_keystringrequired
domainstringrequired

Mailgun sending domain

regionstring | null

Optional Mailgun region hint

activebooleantrue
providerstringsesrequired
access_key_idstringrequired
secret_access_keystringrequired
regionstringrequired

AWS SES region

activebooleantrue
providerstringpostmarkrequired
server_tokenstringrequired

Postmark server token for sending email

account_tokenstringrequired

Postmark account token for domains API access

activebooleantrue
providerstringresendrequired
api_keystringrequired
activebooleantrue
providerstringsendgridrequired
api_keystringrequired
activebooleantrue
providerstringactivecampaignrequired
api_urlstring<uri>required

The API URL from ActiveCampaign Settings > Developer, like https://youraccount.api-us1.com. Only https on an ActiveCampaign API host is accepted.

api_keystringrequiredwrite only
activebooleantrue

IntegrationSyncConfiguration

object
integration_idintegerrequired
providerstringrequired
sync_contractIntegrationSyncContractrequired
Show child attributes
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean

IntegrationSyncContract

object
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean

IntegrationSyncObjectSelection

object
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean

IntegrationSyncTraitMapping

object
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring

IntegrationSyncConfigurationWriteRequest

object
sync_contractIntegrationSyncContractrequired
Show child attributes
versioninteger1required
mirror_listsbooleanrequired
updated_atstring<date-time> | null
Show child attributes
object_idstring
object_slugstringrequired
labelstring
modestringaddressablerelatedrequired
enabledbooleantrue
field_policystringall_supportedselected
selected_fieldsArray<string>
excluded_fieldsArray<string>
relationshipobject
Show child attributes
attribute_slugstring
target_object_slugstringpeopleusers
Show child attributes
kindstringdeal_pipelinerequired
stage_attributestringrequired
closed_stage_valuesArray<string>required
amount_attributestring
currency_attributestring
managed_audience_mapping_keystring
mirror_listsboolean

IntegrationSyncDiscovery

object
providerstringrequired
versioninteger1required
truncatedbooleanrequired
objectsArray<object>required
Show child attributes
object_idstringrequired
object_slugstringrequired
singular_nounstring
plural_nounstring
eligiblebooleanrequired
recommended_modestring | nulladdressablerelated
ineligible_reasonstring | null
attributes_truncatedboolean
Show child attributes
attribute_idstringrequired
attribute_slugstringrequired
titlestring
typestringrequired
classificationstringcanonical_scalarfact_onlyrelationshiprequired
requiredboolean
uniqueboolean
multiselectboolean
target_object_slugsArray<string>
optionsArray<string>
Show child attributes
attribute_idstringrequired
attribute_slugstringrequired
titlestring
typestringrequired
classificationstringcanonical_scalarfact_onlyrelationshiprequired
requiredboolean
uniqueboolean
multiselectboolean
target_object_slugsArray<string>
optionsArray<string>

IntegrationSyncDiscoveredAttribute

object
attribute_idstringrequired
attribute_slugstringrequired
titlestring
typestringrequired
classificationstringcanonical_scalarfact_onlyrelationshiprequired
requiredboolean
uniqueboolean
multiselectboolean
target_object_slugsArray<string>
optionsArray<string>

MailgunIntegrationInput

object
providerstringmailgunrequired
api_keystringrequired
domainstringrequired

Mailgun sending domain

regionstring | null

Optional Mailgun region hint

activebooleantrue

SesIntegrationInput

object
providerstringsesrequired
access_key_idstringrequired
secret_access_keystringrequired
regionstringrequired

AWS SES region

activebooleantrue

PostmarkIntegrationInput

object
providerstringpostmarkrequired
server_tokenstringrequired

Postmark server token for sending email

account_tokenstringrequired

Postmark account token for domains API access

activebooleantrue

ResendIntegrationInput

object
providerstringresendrequired
api_keystringrequired
activebooleantrue

SendgridIntegrationInput

object
providerstringsendgridrequired
api_keystringrequired
activebooleantrue

ActiveCampaignIntegrationInput

object
providerstringactivecampaignrequired
api_urlstring<uri>required

The API URL from ActiveCampaign Settings > Developer, like https://youraccount.api-us1.com. Only https on an ActiveCampaign API host is accepted.

api_keystringrequiredwrite only
activebooleantrue

Plan

object
idinteger
namestring
activeboolean
change_timingstring | nullimmediaterenewal

Available on account-scoped base offers; uses the same rule as subscription change scheduling.

change_atstring<date-time> | null
change_blockersArray<object>

Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.

Show child attributes
resourcestringbrandsdomainsseatsinboxesrequired
usedinteger>= 0required
limitinteger>= 0required
messagestringrequired
probation_recipient_cap_24hinteger>= 0

Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.

standard_recipient_cap_24hinteger>= 0
trusted_recipient_cap_24hinteger>= 0

Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.

Show child attributes
agent_inboxAgentInboxEntitlementrequired
Show child attributes
enabledbooleanrequired
max_inboxesinteger | null>= 0required

Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.

included_inboxesinteger | null>= 0

Effective included allowance

grandfathered_inboxesinteger>= 0
purchased_inboxesinteger>= 0

Confirmed paid units only.

coexistence_inboxesinteger>= 0

Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.

inbound_messages_includedinteger | null>= 0required
inbound_messages_meteredbooleanrequired
inbound_message_overage_rate_centsstringrequired
max_inbound_domainsinteger | null>= 0required
max_apex_domainsinteger | null>= 0required
apex_mxbooleanrequired
legacy_forwardingbooleanrequired
catch_allbooleanrequired
retention_daysinteger | null>= 0required
advanced_queue_controlsbooleanrequired

EmailDesign

object

Email template design document

versionversion>= 1
sectionsArray<EmailSection>
Show child attributes
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger
themetheme

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
heading_sizeinteger
body_sizeinteger
radiusinteger
spacing_densitystringcompactnormalspacious
button_background_colorstring
button_text_colorstring
button_paddingstring
logo_urlstring
company_namestring
physical_addressstring

EmailAccessibilityLint

object

Advisory accessibility lint result for rendered email previews

product_bindingsArray<object>
Show child attributes
pathstring
availableinteger
displayedinteger
truncatedboolean
validboolean

Always true while accessibility lint is advisory-only

Show child attributes
levelstring
Example
warning
rulestring
Example
image_alt_text
messagestring
suggested_fixstring
countinteger
min_rationumber<float>

EmailAccessibilityWarning

object
levelstring
Example
warning
rulestring
Example
image_alt_text
messagestring
suggested_fixstring
countinteger
min_rationumber<float>

EmailSection

object
bindingobject

Product 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.

Show child attributes
pathstringrequired
indexinteger[0, 49]
limitinteger[1, 50]
blockobject

Top-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.

Show child attributes
template_idinteger>= 1required
keystring
typestringheaderherotextimagebuttoncolumnsproductproductsgallerysocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
section_background_colorstring
paddingstring
alignstringleftcenterright
scalestringdisplayposter
font_sizeinteger
text_colorstring
shapestringsquareroundedarchcircle
remove_gapboolean
border_radiusinteger

EmailComponentSpec

object

Full schema for email design sections. Each component has type, description, props (with types, required flags, defaults), and tips.

versionintegerrequired
design_guidelinesstringrequired
renderer_versionstringrequired

The @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.

componentsArray<object>required
Show child attributes
typestringrequired
descriptionstringrequired
tipsArray<string>
propsobjectrequired
Show child attributes
[key: string]object
Show child attributes
typestringrequired
requiredboolean
defaultany
descriptionstring
enumArray<string>
itemsobject
Show child attributes
[key: string]object
Show child attributes
typestringrequired
descriptionstringrequired
server_ownedboolean
unset_when_emptyboolean

An empty value is allowed in a draft; delivery leaves the section out.

theme_keystring
style_attributesArray<object>required

Standard per-section style attribute registry.

Show child attributes
keystringrequired
labelstringrequired
typestringcolorspacingenumnumberbooleanrequired
applies_toanyrequired
defaultany
theme_fallbackstring
descriptionstringrequired
mininteger
maxinteger
valuesArray<string>
targetobjectrequired
Show child attributes
elstringsectioncontentshaperequired
attrstring
preview_documentobjectrequired
Show child attributes
parameterstringrequired
descriptionstringrequired
exampleobjectrequired
variablesobjectrequired

Merge variables grouped by source namespace.

Show child attributes
[key: string]Array<object>
Show child attributes
namestringrequired
descriptionstringrequired
filtersArray<object>required
Show child attributes
namestringrequired
syntaxstringrequired
descriptionstringrequired
theme_attributesArray<object>required

Brand Kit theme attribute registry (single source of truth for the editor).

Show child attributes
keystringrequired
labelstringrequired
typestringcolorfontnumberenumspacingstringimagearrayrequired
defaultany
categorystringcolorfontvisual_identityidentityrequired
slotstring
surfacesArray<string>required
mininteger
maxinteger
valuesArray<string>
optionsArray<object>
Show child attributes
valuestring
labelstring
descriptionstring
transform_tableobject
Show child attributes
[key: string]string
columnboolean
storagestring
placeholderstring
value_resolverstring
server_ownedboolean
descriptionstring

FlowSpec

object

Schema 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.

filtersfilters
Show child attributes
[key: string]object
Show child attributes
titlestring
groupstring
aliasstring

Internal field binding.

summarystring
typestringstringnumberbooleandateenumlistevent
predicatesArray<string>
enum_valuesArray<string>
event_name_sourcestring
recency_optionsArray<string>
sort_keystring

Optional contacts index sort key backed by this filter.

sort_columnstring

Internal SQL column used for server-side sorting.

triggersArray<object>
Show child attributes
titlestring
eventstring
descriptionstring

What fires the trigger.

variablesobject
Show child attributes
pathsArray<object>
Show child attributes
pathstring

Declared event payload path.

typestringstringintegernumberbooleanobjectarray
filtersfilters
Show child attributes
[key: string]object
Show child attributes
titlestring
groupstring
aliasstring

Internal field binding.

summarystring
typestringstringnumberbooleandateenumlistevent
predicatesArray<string>
enum_valuesArray<string>
event_name_sourcestring
recency_optionsArray<string>
sort_keystring

Optional contacts index sort key backed by this filter.

sort_columnstring

Internal SQL column used for server-side sorting.

filter_limitsobject

Limits every filter tree is held to on save. A tree past either limit is refused with invalid_filter.

Show child attributes
max_depthinteger

The deepest level a node may sit at. An explicit root group ({ op, conditions }) is level 0 and its conditions level 1; each nested group or NOT adds one level. A legacy bare-array root puts its items at level 0.

max_conditions_per_groupinteger

The most conditions one group may hold.

stepsArray<object>
Show child attributes
typestring
titlestring
summarystring
paramsobject
Show child attributes
[key: string]object
Show child attributes
labelstring
typestring
requiredboolean
defaultany
descriptionstring