# Nitrosend API

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:
```json
{
  "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"`.


Version: 1.1.6

Authentication:
- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.
- ManagementCredential: http (bearer). One-time-revealed operator_v1 credential pinned to one active management grant and Brand.

## Probe the MCP OAuth endpoint

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 401: MCP authentication required

Content type: application/json

Type: object

Additional properties: true

- 405: Authenticated GET is not supported by the MCP transport

Content type: application/json

Type: object

Additional properties: true

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/mcp' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/mcp', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/mcp',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## MCP JSON-RPC endpoint

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Additional properties: true

Responses:

- 200: JSON-RPC response

Content type: application/json

Type: object

Additional properties: true

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/mcp' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/mcp',
    data='{}'.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Personal Agent Protocol discovery document

`GET /.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.


Authentication: no security requirement declared for this operation.

Responses:

- 200: The discovery document

Content type: application/json

Type: object

- `protocol_version` (required)
  Type: string
  
  Example:
  
  ```json
  "1.0"
  ```

- `organization` (required)
  Type: object
  
  - `name` (required)
    Type: string
    
    Example:
    
    ```json
    "Nitrosend"
    ```
  
  - `domain` (required)
    Type: string
    
    Example:
    
    ```json
    "api.nitrosend.com"
    ```

- `auth` (optional)
  Type: object
  
  - `scopes` (optional)
    Type: object
    
    Additional properties: 
      Type: string
  
  - `scope_hints` (optional)
    Type: object
    
    Additional properties: 
      Type: object
      
      - `changes` (optional)
        Type: string
        
        enum: ["none","reversible","irreversible"]
      
      - `personal_data` (optional)
        Type: boolean

- `apis` (required)
  Type: array
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
      
      Example:
      
      ```json
      "mcp"
      ```
    
    - `url` (required)
      Type: string, uri
    
    - `description` (optional)
      Type: string

- `extensions` (optional)
  Type: object
  
  Additional properties: 
    Type: array
    
    Items:
      Type: object
      
      - `version` (required)
        Type: string
      
      Additional properties: true

- 404: Poppy is off, or the request is not for the canonical API origin

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/.well-known/poppy.json'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/.well-known/poppy.json', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/.well-known/poppy.json')
print(response.text)
```


## Begin email-verified signup

`POST /v1/signup`

Authentication: no security requirement declared for this operation.

Parameters:

- `X-Nitrosend-Device-Type` (header, string, optional) - Bounded client-declared signup measurement; never authentication or account authority. OAuth preserves it through the existing signed attribution context.
  Type: string
  
  enum: ["computer","phone","tablet"]

- `X-Nitrosend-In-App-Browser` (header, string, optional) - Bounded client-declared embedded browser measurement. Omitted or unknown is unclassified, not proof of a standalone browser.
  Type: string
  
  enum: ["Instagram","Facebook","TikTok","LinkedIn","X","Google app","this app"]

Request body: application/json (required)

Type: object

- `user` (required)
  Type: object
  
  - `first_name` (optional)
    Type: string
  
  - `last_name` (optional)
    Type: string
  
  - `email` (required)
    Type: string, email
  
  - `mobile` (optional)
    Type: string
  
  - `invite_token` (optional)
    Type: string; nullable
  
  - `referral_code` (optional)
    Type: string; nullable
    
    Partner or referral code. The signup succeeds even when the code is invalid; the outcome is reported in `meta.promo`.
  
  - `rewardful_referral_id` (optional)
    Type: string; nullable
  
  - `signup_intent` (optional)
    Reference: [SignupIntent](https://docs.nitrosend.com/api/schemas/signupintent-30dbbeb7e4.md); Type: string; nullable
    
    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.
    
    enum: ["agency"]
  
  - `password` (required)
    Type: string, password
    
    minLength: 6
  
  - `password_confirmation` (optional)
    Type: string, password
  
  - `attribution_context` (optional)
    Reference: [FirstTouchAttributionContext](https://docs.nitrosend.com/api/schemas/firsttouchattributioncontext-13e66f28c9.md); Type: 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.

Responses:

- 409: Verification required. No account, membership, API key or session has been created. The same response covers existing addresses; sign in if already registered.

Content type: application/json

Type: object

Schema: [SignupVerificationRequired](https://docs.nitrosend.com/api/schemas/signupverificationrequired-10eee67b47.md)

- `status` (required)
  Type: string
  
  enum: ["verification_required"]

- `error_code` (optional)
  Type: string
  
  enum: ["verification_required"]

- `next_action` (required)
  Type: string
  
  enum: ["verify_email"]

- `message` (required)
  Type: string

- `error` (optional)
  Type: boolean

- `code` (optional)
  Type: integer

- `verification_expires_in` (optional)
  Type: integer
  
  Example:
  
  ```json
  1800
  ```

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 429: 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.

Content type: application/json

Type: object

- `error_code` (optional)
  Type: string
  
  enum: ["signup_capacity_reached"]

- `message` (optional)
  Type: string

- `next_action` (optional)
  Type: string

- 503: Signup paused or mail could not be queued. Retry later.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/signup' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user": {
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "mobile": "string",
    "invite_token": "string",
    "referral_code": "string",
    "rewardful_referral_id": "string",
    "signup_intent": "agency",
    "password": "********",
    "password_confirmation": "********",
    "attribution_context": {
      "landing_url": "string",
      "referrer_url": "string",
      "captured_at": "2024-01-15T09:30:00Z",
      "utm_source": "string",
      "utm_medium": "string",
      "utm_campaign": "string",
      "utm_content": "string",
      "utm_term": "string",
      "fbclid": "string",
      "ttclid": "string"
    }
  }
}'
```

### JavaScript

```javascript
const body = `{
  "user": {
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "mobile": "string",
    "invite_token": "string",
    "referral_code": "string",
    "rewardful_referral_id": "string",
    "signup_intent": "agency",
    "password": "********",
    "password_confirmation": "********",
    "attribution_context": {
      "landing_url": "string",
      "referrer_url": "string",
      "captured_at": "2024-01-15T09:30:00Z",
      "utm_source": "string",
      "utm_medium": "string",
      "utm_campaign": "string",
      "utm_content": "string",
      "utm_term": "string",
      "fbclid": "string",
      "ttclid": "string"
    }
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "user": {
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "mobile": "string",
    "invite_token": "string",
    "referral_code": "string",
    "rewardful_referral_id": "string",
    "signup_intent": "agency",
    "password": "********",
    "password_confirmation": "********",
    "attribution_context": {
      "landing_url": "string",
      "referrer_url": "string",
      "captured_at": "2024-01-15T09:30:00Z",
      "utm_source": "string",
      "utm_medium": "string",
      "utm_campaign": "string",
      "utm_content": "string",
      "utm_term": "string",
      "fbclid": "string",
      "ttclid": "string"
    }
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/signup',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Request an email verification link

`POST /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.

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `email` (required)
  Type: string, email

Responses:

- 202: If eligible, verification mail is queued. No credential is returned.

Content type: application/json

Type: object

Schema: [SignupVerificationRequired](https://docs.nitrosend.com/api/schemas/signupverificationrequired-10eee67b47.md)

- `status` (required)
  Type: string
  
  enum: ["verification_required"]

- `error_code` (optional)
  Type: string
  
  enum: ["verification_required"]

- `next_action` (required)
  Type: string
  
  enum: ["verify_email"]

- `message` (required)
  Type: string

- `error` (optional)
  Type: boolean

- `code` (optional)
  Type: integer

- `verification_expires_in` (optional)
  Type: integer
  
  Example:
  
  ```json
  1800
  ```

- 429: 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.

Content type: application/json

Type: object

- `error_code` (optional)
  Type: string
  
  enum: ["signup_capacity_reached"]

- `message` (optional)
  Type: string

- `next_action` (optional)
  Type: string

- 503: Mail could not be queued. Retry later.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/signup/resend' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com"
}'
```

### JavaScript

```javascript
const body = `{
  "email": "user@example.com"
}`;

const response = await fetch('https://api.nitrosend.com/v1/signup/resend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "email": "user@example.com"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/signup/resend',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Prove email ownership and complete signup

`POST /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.


Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `token` (required)
  Type: string, password
  
  writeOnly: true

- `password` (optional)
  Type: string, password
  
  Required to complete a new password signup.
  
  minLength: 6
  
  writeOnly: true

Responses:

- 200: Signup complete, or an established email change confirmed.

Content type: application/json

Type: unknown

oneOf:
  Reference: [SignupSession](https://docs.nitrosend.com/api/schemas/signupsession-e16b022019.md); Type: SignupSession

  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["email_verified"]
  
  - `next_action` (required)
    Type: string
    
    enum: ["sign_in"]

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 429: 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.

Content type: application/json

Type: object

- `error_code` (optional)
  Type: string
  
  enum: ["signup_capacity_reached"]

- `message` (optional)
  Type: string

- `next_action` (optional)
  Type: string

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

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/signup/verify' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "token": "********",
  "password": "********"
}'
```

### JavaScript

```javascript
const body = `{
  "token": "********",
  "password": "********"
}`;

const response = await fetch('https://api.nitrosend.com/v1/signup/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "token": "********",
  "password": "********"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/signup/verify',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Resume an already verified signup

`POST /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.

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `email` (required)
  Type: string, email

- `password` (required)
  Type: string, password
  
  writeOnly: true

Responses:

- 200: Active session

Content type: application/json

Type: SignupSession

Schema: [SignupSession](https://docs.nitrosend.com/api/schemas/signupsession-e16b022019.md)

allOf:
  Reference: [User](https://docs.nitrosend.com/api/schemas/user-b512d97e7c.md); Type: object

  Type: object
  
  - `meta` (optional)
    Type: object
    
    - `account_id` (optional)
      Type: integer; nullable
    
    - `promo` (optional)
      Reference: [SignupPromoResult](https://docs.nitrosend.com/api/schemas/signuppromoresult-244d693d08.md); Type: object

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 429: 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.

Content type: application/json

Type: object

- `error_code` (optional)
  Type: string
  
  enum: ["signup_capacity_reached"]

- `message` (optional)
  Type: string

- `next_action` (optional)
  Type: string

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

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/signup/activate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "password": "********"
}'
```

### JavaScript

```javascript
const body = `{
  "email": "user@example.com",
  "password": "********"
}`;

const response = await fetch('https://api.nitrosend.com/v1/signup/activate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "email": "user@example.com",
  "password": "********"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/signup/activate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Sign in and receive a JWT

`POST /v1/login`

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `user` (required)
  Type: object
  
  - `email` (required)
    Type: string, email
  
  - `password` (required)
    Type: string, password

Responses:

- 200: Signed in

Content type: application/json

Type: unknown

allOf:
  Reference: [User](https://docs.nitrosend.com/api/schemas/user-b512d97e7c.md); Type: object

  Type: object
  
  - `meta` (optional)
    Type: object
    
    Present when the user has an account.
    
    - `account_id` (optional)
      Type: integer
      
      The account this sign-in opens on. Send it as X-Account-ID to act on that account.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: 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.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user": {
    "email": "user@example.com",
    "password": "********"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "user": {
    "email": "user@example.com",
    "password": "********"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "user": {
    "email": "user@example.com",
    "password": "********"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/login',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Sign out and revoke JWT

`DELETE /v1/logout`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 204: Signed out

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/logout' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/logout', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/logout',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get OAuth popup context

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `client_id` (query, string, optional) - OAuth application ID, used to name the connection being authorized.
  Type: string

Responses:

- 200: Popup context

Content type: application/json

Type: object

Schema: [OAuthPopupContext](https://docs.nitrosend.com/api/schemas/oauthpopupcontext-3e0eea70a1.md)

- `application_name` (optional)
  Type: string; nullable

- `email` (optional)
  Type: string
  
  The signed-in person's address, where an agent's first test goes.

- `accounts` (required)
  Type: array
  
  Items:
    Reference: [OAuthPopupAccount](https://docs.nitrosend.com/api/schemas/oauthpopupaccount-aaffe1b73b.md); Type: object

- `plans` (required)
  Type: array
  
  Items:
    Reference: [OAuthPopupPlan](https://docs.nitrosend.com/api/schemas/oauthpopupplan-91cd787e2f.md); Type: object

- `stripe_publishable_key` (optional)
  Type: string; nullable

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

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

Content type: application/json

Type: object

- `error` (required)
  Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/oauth/me' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/oauth/me', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/oauth/me',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Subscribe the selected OAuth popup account

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [OAuthPopupSubscribeRequest](https://docs.nitrosend.com/api/schemas/oauthpopupsubscriberequest-d7e8777501.md)

- `plan_id` (required)
  Type: integer

- `account_id` (optional)
  Type: integer; nullable

- `stripe_token` (optional)
  Type: string; nullable

Responses:

- 200: Popup can continue to consent

Content type: application/json

Type: object

Schema: [OAuthPopupSubscribeResponse](https://docs.nitrosend.com/api/schemas/oauthpopupsubscriberesponse-61bd3748f0.md)

- `next_step` (required)
  Type: string
  
  enum: ["consent"]

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: 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.

Content type: application/json

Type: object

- `error` (required)
  Type: string

- `billing_route` (optional)
  Type: object
  
  Present when the account bills through another provider.

- 422: Account or plan selection failed

Content type: application/json

Type: object

- `error` (required)
  Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/oauth/subscribe' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "plan_id": 0,
  "account_id": 0,
  "stripe_token": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "plan_id": 0,
  "account_id": 0,
  "stripe_token": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/oauth/subscribe', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "plan_id": 0,
  "account_id": 0,
  "stripe_token": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/oauth/subscribe',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Create a CSRF-safe OAuth provider launch URL

`POST /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.


Authentication: no security requirement declared for this operation.

Parameters:

- `X-Nitrosend-Device-Type` (header, string, optional) - Bounded client-declared signup measurement; never authentication or account authority. OAuth preserves it through the existing signed attribution context.
  Type: string
  
  enum: ["computer","phone","tablet"]

- `X-Nitrosend-In-App-Browser` (header, string, optional) - Bounded client-declared embedded browser measurement. Omitted or unknown is unclassified, not proof of a standalone browser.
  Type: string
  
  enum: ["Instagram","Facebook","TikTok","LinkedIn","X","Google app","this app"]

Request body: application/json (required)

Type: object

Schema: [OAuthLaunchRequest](https://docs.nitrosend.com/api/schemas/oauthlaunchrequest-ccb6184314.md)

- `provider` (required)
  Type: string
  
  enum: ["google_oauth2","github"]

- `auth_intent` (optional)
  Type: string
  
  default: "app"
  
  enum: ["app","agent"]

- `auth_step` (optional)
  Type: string
  
  default: "login"
  
  enum: ["login","signup"]

- `resume_url` (optional)
  Type: string, uri; nullable
  
  Required when `auth_intent=agent`; must point to the frontend `/oauth/connect` route.

- `invite_token` (optional)
  Type: string; nullable

- `referral_code` (optional)
  Type: string; nullable

- `rewardful_referral_id` (optional)
  Type: string; nullable

- `attribution_context` (optional)
  Reference: [FirstTouchAttributionContext](https://docs.nitrosend.com/api/schemas/firsttouchattributioncontext-13e66f28c9.md); Type: 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.

- `signup_intent` (optional)
  Reference: [SignupIntent](https://docs.nitrosend.com/api/schemas/signupintent-30dbbeb7e4.md); Type: string; nullable
  
  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.
  
  enum: ["agency"]

Responses:

- 200: Launch URL created

Content type: application/json

Type: object

Schema: [OAuthLaunchResponse](https://docs.nitrosend.com/api/schemas/oauthlaunchresponse-e938698fe1.md)

- `launch_url` (required)
  Type: string, uri

- 400: Invalid provider or resume URL

Content type: application/json

Type: object

- `error` (required)
  Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/oauth/launch' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "provider": "google_oauth2",
  "auth_intent": "app",
  "auth_step": "login",
  "resume_url": "https://example.com",
  "invite_token": "string",
  "referral_code": "string",
  "rewardful_referral_id": "string",
  "attribution_context": {
    "landing_url": "string",
    "referrer_url": "string",
    "captured_at": "2024-01-15T09:30:00Z",
    "utm_source": "string",
    "utm_medium": "string",
    "utm_campaign": "string",
    "utm_content": "string",
    "utm_term": "string",
    "fbclid": "string",
    "ttclid": "string"
  },
  "signup_intent": "agency"
}'
```

### JavaScript

```javascript
const body = `{
  "provider": "google_oauth2",
  "auth_intent": "app",
  "auth_step": "login",
  "resume_url": "https://example.com",
  "invite_token": "string",
  "referral_code": "string",
  "rewardful_referral_id": "string",
  "attribution_context": {
    "landing_url": "string",
    "referrer_url": "string",
    "captured_at": "2024-01-15T09:30:00Z",
    "utm_source": "string",
    "utm_medium": "string",
    "utm_campaign": "string",
    "utm_content": "string",
    "utm_term": "string",
    "fbclid": "string",
    "ttclid": "string"
  },
  "signup_intent": "agency"
}`;

const response = await fetch('https://api.nitrosend.com/v1/oauth/launch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "provider": "google_oauth2",
  "auth_intent": "app",
  "auth_step": "login",
  "resume_url": "https://example.com",
  "invite_token": "string",
  "referral_code": "string",
  "rewardful_referral_id": "string",
  "attribution_context": {
    "landing_url": "string",
    "referrer_url": "string",
    "captured_at": "2024-01-15T09:30:00Z",
    "utm_source": "string",
    "utm_medium": "string",
    "utm_campaign": "string",
    "utm_content": "string",
    "utm_term": "string",
    "fbclid": "string",
    "ttclid": "string"
  },
  "signup_intent": "agency"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/oauth/launch',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get current user profile

`GET /v1/my/user`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: User profile

Content type: application/json

Type: object

Schema: [User](https://docs.nitrosend.com/api/schemas/user-b512d97e7c.md)

- `id` (optional)
  Type: integer

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `email` (optional)
  Type: string, email

- `email_verified_at` (optional)
  Type: string, date-time; nullable
  
  Actual email proof time; legacy access does not fabricate proof.

- `unconfirmed_email` (optional)
  Type: string, email; nullable
  
  Requested email change awaiting proof. Continue signing in with email until confirmation.

- `signup_completed_at` (optional)
  Type: string, date-time; nullable

- `mobile` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `time_zone` (optional)
  Type: string; nullable

- `admin` (optional)
  Type: boolean

- `ui_login_count` (optional)
  Type: integer
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/user' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/user', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/user',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update current user profile

`PATCH /v1/my/user`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `first_name` (optional)
  Type: string

- `last_name` (optional)
  Type: string

- `email` (optional)
  Type: unknown
  
  oneOf:
    Type: string, email
  
    Type: array
    
    Items:
      Type: string, email

- `mobile` (optional)
  Type: string

- `time_zone` (optional)
  Type: string; nullable

Responses:

- 200: Updated user

Content type: application/json

Type: object

Schema: [User](https://docs.nitrosend.com/api/schemas/user-b512d97e7c.md)

- `id` (optional)
  Type: integer

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `email` (optional)
  Type: string, email

- `email_verified_at` (optional)
  Type: string, date-time; nullable
  
  Actual email proof time; legacy access does not fabricate proof.

- `unconfirmed_email` (optional)
  Type: string, email; nullable
  
  Requested email change awaiting proof. Continue signing in with email until confirmation.

- `signup_completed_at` (optional)
  Type: string, date-time; nullable

- `mobile` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `time_zone` (optional)
  Type: string; nullable

- `admin` (optional)
  Type: boolean

- `ui_login_count` (optional)
  Type: integer
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/user' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "time_zone": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "time_zone": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/user', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "time_zone": "string"
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/user',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get current impersonation status

`GET /v1/my/impersonation`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Current impersonation state

Content type: application/json

Type: object

Schema: [ImpersonationStatus](https://docs.nitrosend.com/api/schemas/impersonationstatus-aeed4cfe3b.md)

- `impersonating` (required)
  Type: boolean

- `impersonator` (required)
  Type: unknown
  
  oneOf:
    Reference: [Impersonator](https://docs.nitrosend.com/api/schemas/impersonator-29bed20d4d.md); Type: object
  
    Type: null

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/impersonation' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/impersonation', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/impersonation',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Revoke the active impersonation session

`DELETE /v1/my/impersonation`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Impersonation session revoked

Content type: application/json

Type: object

Schema: [ImpersonationExit](https://docs.nitrosend.com/api/schemas/impersonationexit-41e1119d4e.md)

- `redirect_url` (required)
  Type: string, uri
  
  Example:
  
  ```json
  "https://api.nitrosend.com/adm"
  ```

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/impersonation' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/impersonation', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/impersonation',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get the current account's Affiliate Center

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Affiliate Center payload or temporary setup state

Content type: application/json

Type: object

Schema: [AffiliateCenterPayload](https://docs.nitrosend.com/api/schemas/affiliatecenterpayload-833d1dde5c.md)

- `enrolled` (required)
  Type: boolean
  
  Whether the account is linked to a Rewardful affiliate.

- `available` (required)
  Type: boolean
  
  Whether live affiliate data or setup is currently available.

- `state` (optional)
  Type: string; nullable
  
  enum: ["active","paused","unavailable"]

- `setup_status` (optional)
  Type: string; nullable
  
  Present only while an entitled, unlinked account is being reconciled.
  
  enum: ["pending","needs_details","unavailable"]

- `share_url` (optional)
  Type: string, uri; nullable

- `stats` (optional)
  Type: object
  
  - `visitors` (optional)
    Type: integer
    
    minimum: 0
  
  - `leads` (optional)
    Type: integer
    
    minimum: 0
  
  - `conversions` (optional)
    Type: integer
    
    minimum: 0

- `earnings` (optional)
  Type: object
  
  - `known` (optional)
    Type: boolean
  
  - `total_cents` (optional)
    Type: integer; nullable
  
  - `currency` (optional)
    Type: string

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/affiliate' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/affiliate', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/affiliate',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Reconcile the current account's affiliate immediately

`POST /v1/my/affiliate`

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

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json

Type: object

- `first_name` (optional)
  Type: string

- `last_name` (optional)
  Type: string

Responses:

- 200: Existing or already-linked affiliate

Content type: application/json

Type: object

Schema: [AffiliateCenterPayload](https://docs.nitrosend.com/api/schemas/affiliatecenterpayload-833d1dde5c.md)

- `enrolled` (required)
  Type: boolean
  
  Whether the account is linked to a Rewardful affiliate.

- `available` (required)
  Type: boolean
  
  Whether live affiliate data or setup is currently available.

- `state` (optional)
  Type: string; nullable
  
  enum: ["active","paused","unavailable"]

- `setup_status` (optional)
  Type: string; nullable
  
  Present only while an entitled, unlinked account is being reconciled.
  
  enum: ["pending","needs_details","unavailable"]

- `share_url` (optional)
  Type: string, uri; nullable

- `stats` (optional)
  Type: object
  
  - `visitors` (optional)
    Type: integer
    
    minimum: 0
  
  - `leads` (optional)
    Type: integer
    
    minimum: 0
  
  - `conversions` (optional)
    Type: integer
    
    minimum: 0

- `earnings` (optional)
  Type: object
  
  - `known` (optional)
    Type: boolean
  
  - `total_cents` (optional)
    Type: integer; nullable
  
  - `currency` (optional)
    Type: string

- 201: Affiliate identity linked to the account

Content type: application/json

Type: object

Schema: [AffiliateCenterPayload](https://docs.nitrosend.com/api/schemas/affiliatecenterpayload-833d1dde5c.md)

- `enrolled` (required)
  Type: boolean
  
  Whether the account is linked to a Rewardful affiliate.

- `available` (required)
  Type: boolean
  
  Whether live affiliate data or setup is currently available.

- `state` (optional)
  Type: string; nullable
  
  enum: ["active","paused","unavailable"]

- `setup_status` (optional)
  Type: string; nullable
  
  Present only while an entitled, unlinked account is being reconciled.
  
  enum: ["pending","needs_details","unavailable"]

- `share_url` (optional)
  Type: string, uri; nullable

- `stats` (optional)
  Type: object
  
  - `visitors` (optional)
    Type: integer
    
    minimum: 0
  
  - `leads` (optional)
    Type: integer
    
    minimum: 0
  
  - `conversions` (optional)
    Type: integer
    
    minimum: 0

- `earnings` (optional)
  Type: object
  
  - `known` (optional)
    Type: boolean
  
  - `total_cents` (optional)
    Type: integer; nullable
  
  - `currency` (optional)
    Type: string

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 503: Upstream service unavailable

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/affiliate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "first_name": "string",
  "last_name": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/affiliate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "first_name": "string",
  "last_name": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/affiliate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get account details

`GET /v1/my/account`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

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

Content type: application/json

Type: object

Schema: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `avatar` (optional)
  Type: string; nullable
  
  Signed blob ID

- `banner` (optional)
  Type: string; nullable
  
  Signed blob ID

- `commercial_tier` (optional)
  Type: string
  
  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.
  
  enum: ["unsubscribed","free","setup","starter","pro","growth","scale","ultra","enterprise"]

- `safe_mode_enabled` (optional)
  Type: boolean

- `access` (optional)
  Reference: [AccountAccess](https://docs.nitrosend.com/api/schemas/accountaccess-afca59462c.md); Type: object

- `billing` (optional)
  Type: unknown
  
  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.
  
  oneOf:
    Reference: [AccountBilling](https://docs.nitrosend.com/api/schemas/accountbilling-0761bdeffb.md); Type: object
    
    Billing for direct access (owners, admins and members, and their own credentials).
  
    Reference: [DelegatedAccountBilling](https://docs.nitrosend.com/api/schemas/delegatedaccountbilling-1d025108d9.md); Type: 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.

- `team` (optional)
  Type: object
  
  Present for direct access and omitted from delegated account projections.
  
  - `seat_limit` (optional)
    Type: integer
  
  - `seat_count` (optional)
    Type: integer
  
  - `member_count` (optional)
    Type: integer
  
  - `invite_count` (optional)
    Type: integer
  
  - `current_role` (optional)
    Type: string; nullable
  
  - `can_manage_team` (optional)
    Type: boolean

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update account settings

`PATCH /v1/my/account`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `avatar` (optional)
  Type: string
  
  Signed blob ID

- `banner` (optional)
  Type: string
  
  Signed blob ID

Responses:

- 200: Updated account

Content type: application/json

Type: object

Schema: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `avatar` (optional)
  Type: string; nullable
  
  Signed blob ID

- `banner` (optional)
  Type: string; nullable
  
  Signed blob ID

- `commercial_tier` (optional)
  Type: string
  
  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.
  
  enum: ["unsubscribed","free","setup","starter","pro","growth","scale","ultra","enterprise"]

- `safe_mode_enabled` (optional)
  Type: boolean

- `access` (optional)
  Reference: [AccountAccess](https://docs.nitrosend.com/api/schemas/accountaccess-afca59462c.md); Type: object

- `billing` (optional)
  Type: unknown
  
  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.
  
  oneOf:
    Reference: [AccountBilling](https://docs.nitrosend.com/api/schemas/accountbilling-0761bdeffb.md); Type: object
    
    Billing for direct access (owners, admins and members, and their own credentials).
  
    Reference: [DelegatedAccountBilling](https://docs.nitrosend.com/api/schemas/delegatedaccountbilling-1d025108d9.md); Type: 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.

- `team` (optional)
  Type: object
  
  Present for direct access and omitted from delegated account projections.
  
  - `seat_limit` (optional)
    Type: integer
  
  - `seat_count` (optional)
    Type: integer
  
  - `member_count` (optional)
    Type: integer
  
  - `invite_count` (optional)
    Type: integer
  
  - `current_role` (optional)
    Type: string; nullable
  
  - `can_manage_team` (optional)
    Type: boolean

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/account' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "avatar": "string",
  "banner": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "avatar": "string",
  "banner": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/account', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "avatar": "string",
  "banner": "string"
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/account',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Inspect the email sending allowance and pacing

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Current email sender-capacity and pacing projection

Content type: application/json

Type: object

Schema: [DeliveryStatus](https://docs.nitrosend.com/api/schemas/deliverystatus-981154d836.md)

- `assessment_scope` (required)
  Type: string
  
  const: "account_capacity"

- `admission_status` (required)
  Type: string
  
  enum: ["allowed","deferred","denied"]

- `sending_pause` (optional)
  Reference: [SendingPause](https://docs.nitrosend.com/api/schemas/sendingpause-17f8373ff7.md); Type: 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.

- `commercial_capacity` (required)
  Reference: [DeliveryCapacity](https://docs.nitrosend.com/api/schemas/deliverycapacity-bff017be39.md); Type: object

- `shared_abuse_capacity` (required)
  Reference: [SharedAbuseCapacity](https://docs.nitrosend.com/api/schemas/sharedabusecapacity-89ccf276b4.md); Type: object
  
  Retired shared probation allowance. Status is always not_applicable; the field remains for compatibility.

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `pacing_state` (required)
  Reference: [DeliveryPacingState](https://docs.nitrosend.com/api/schemas/deliverypacingstate-b44b7430ca.md); Type: object

- `blocking_control` (optional)
  Type: string
  
  enum: ["account_status","brand","sender_identity","commercial_capacity","shared_abuse_capacity"]

- `reason_code` (optional)
  Type: string

- `issues` (required)
  Type: array
  
  Items:
    Reference: [DeliveryStatusIssue](https://docs.nitrosend.com/api/schemas/deliverystatusissue-9621134fee.md); Type: object

- `retry_at` (optional)
  Type: string, date-time

- `observed_at` (required)
  Type: string, date-time

Additional properties: false

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/delivery/status' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/delivery/status', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/delivery/status',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Quote explicit prepaid email validation

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [ValidationAudience](https://docs.nitrosend.com/api/schemas/validationaudience-794b45cf09.md)

- `lead_ids` (optional)
  Type: array
  
  Explicit Lead selection in the current Brand. Does not create marketing Contacts or require a discovery search.
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer
    
    minimum: 1

- `contact_channel_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer

- `contact_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer

- `list_id` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer

- `all_contacts` (optional)
  Type: boolean
  
  All email channels in the current Brand, subject to the 100000-candidate operation bound.
  
  const: true

- `quote_digest` (optional)
  Type: string
  
  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.
  
  pattern: "^[0-9a-f]{64}$"

oneOf:
  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

Additional properties: false

Responses:

- 200: Non-mutating validation quote

Content type: application/json

Type: object

Schema: [ValidationOperationQuote](https://docs.nitrosend.com/api/schemas/validationoperationquote-44c858f218.md)

- `status` (required)
  Type: string
  
  enum: ["quoted","needs_funding"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `quote_digest` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `mutation` (required)
  Type: boolean
  
  const: false

Additional properties: false

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/validation_operations/quote' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations/quote', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/validation_operations/quote',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## The brand's latest contact list verifications

`GET /v1/my/validation_operations`

Newest first, contact audiences only. Use the operation_id with the show endpoint for results and the sending choice.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `limit` (query, integer, optional)
  Type: integer
  
  default: 5
  
  minimum: 1
  
  maximum: 20

Responses:

- 200: Latest verifications

Content type: application/json

Type: object

- `operations` (required)
  Type: array
  
  Items:
    Type: object
    
    - `operation_id` (required)
      Type: string
    
    - `status` (required)
      Type: string
    
    - `terminal` (required)
      Type: boolean
      
      The run has finished.
    
    - `source_kind` (required)
      Type: string
    
    - `candidate_count` (required)
      Type: integer
      
      minimum: 0
    
    - `created_at` (required)
      Type: string, date-time
    
    - `completed_at` (optional)
      Type: string, date-time
    
    - `failure_code` (optional)
      Type: string
      
      Present when the run stopped or expired before every check finished.
    
    Additional properties: false

Additional properties: false

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/validation_operations?limit=5' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations?limit=5', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/validation_operations?limit=5',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Start or resume explicit prepaid email validation

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required) - Exact-request idempotency key; changed normalized input conflicts.
  Type: string
  
  minLength: 8
  
  maxLength: 255

Request body: application/json (required)

Type: object

Schema: [ValidationAudience](https://docs.nitrosend.com/api/schemas/validationaudience-794b45cf09.md)

- `lead_ids` (optional)
  Type: array
  
  Explicit Lead selection in the current Brand. Does not create marketing Contacts or require a discovery search.
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer
    
    minimum: 1

- `contact_channel_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer

- `contact_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer

- `list_id` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer

- `all_contacts` (optional)
  Type: boolean
  
  All email channels in the current Brand, subject to the 100000-candidate operation bound.
  
  const: true

- `quote_digest` (optional)
  Type: string
  
  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.
  
  pattern: "^[0-9a-f]{64}$"

oneOf:
  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

Additional properties: false

Responses:

- 202: Durable validation operation accepted or replayed

Content type: application/json

Type: object

Schema: [ValidationOperation](https://docs.nitrosend.com/api/schemas/validationoperation-3893a00de8.md)

- `operation_id` (required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

- `status` (required)
  Type: string
  
  enum: ["requested","quoted","held","executing","partially_committed","committed","released","needs_funding","failed"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `item_detail` (required)
  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["available","compacted"]
  
  - `compacted_at` (optional)
    Type: string, date-time
  
  - `item_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `results` (optional)
  Type: object
  
  Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.
  
  - `valid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `invalid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `disposable_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `unknown_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `catchall_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `unconfirmed` (optional)
  Type: object
  
  Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.
  
  - `excluded_count` (optional)
    Type: integer
    
    Addresses this run currently holds out of sends.
    
    minimum: 0
  
  - `sendable_count` (optional)
    Type: integer
    
    This run's unknown and catch-all addresses still in sends.
    
    minimum: 0
  
  - `pending` (optional)
    Type: boolean
    
    The run is still leaving its unconfirmed addresses out.
  
  - `kept_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `kept_at` (optional)
    Type: string, date-time
  
  - `can_include` (optional)
    Type: boolean
    
    Including this run's left-out addresses can be requested now.
  
  - `can_leave_out` (optional)
    Type: boolean
    
    Leaving this run's sendable unconfirmed addresses out can be requested now.
  
  - `include_blocked` (optional)
    Type: boolean
    
    Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.
  
  Additional properties: false

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `failure_code` (optional)
  Type: string

- `started_at` (optional)
  Type: string, date-time

- `completed_at` (optional)
  Type: string, date-time

- `next_action` (optional)
  Type: string

Additional properties: false

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/validation_operations' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/validation_operations',
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get an email validation operation

`GET /v1/my/validation_operations/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Opaque operation_id returned by the create endpoint.
  Type: string
  
  minLength: 32
  
  maxLength: 64

Responses:

- 200: Current durable operation state

Content type: application/json

Type: object

Schema: [ValidationOperation](https://docs.nitrosend.com/api/schemas/validationoperation-3893a00de8.md)

- `operation_id` (required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

- `status` (required)
  Type: string
  
  enum: ["requested","quoted","held","executing","partially_committed","committed","released","needs_funding","failed"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `item_detail` (required)
  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["available","compacted"]
  
  - `compacted_at` (optional)
    Type: string, date-time
  
  - `item_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `results` (optional)
  Type: object
  
  Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.
  
  - `valid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `invalid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `disposable_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `unknown_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `catchall_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `unconfirmed` (optional)
  Type: object
  
  Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.
  
  - `excluded_count` (optional)
    Type: integer
    
    Addresses this run currently holds out of sends.
    
    minimum: 0
  
  - `sendable_count` (optional)
    Type: integer
    
    This run's unknown and catch-all addresses still in sends.
    
    minimum: 0
  
  - `pending` (optional)
    Type: boolean
    
    The run is still leaving its unconfirmed addresses out.
  
  - `kept_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `kept_at` (optional)
    Type: string, date-time
  
  - `can_include` (optional)
    Type: boolean
    
    Including this run's left-out addresses can be requested now.
  
  - `can_leave_out` (optional)
    Type: boolean
    
    Leaving this run's sendable unconfirmed addresses out can be requested now.
  
  - `include_blocked` (optional)
    Type: boolean
    
    Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.
  
  Additional properties: false

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `failure_code` (optional)
  Type: string

- `started_at` (optional)
  Type: string, date-time

- `completed_at` (optional)
  Type: string, date-time

- `next_action` (optional)
  Type: string

Additional properties: false

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/validation_operations/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/validation_operations/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Keep a finished run's unknown and catch-all addresses in sends

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

Responses:

- 200: Updated operation state

Content type: application/json

Type: object

Schema: [ValidationOperation](https://docs.nitrosend.com/api/schemas/validationoperation-3893a00de8.md)

- `operation_id` (required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

- `status` (required)
  Type: string
  
  enum: ["requested","quoted","held","executing","partially_committed","committed","released","needs_funding","failed"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `item_detail` (required)
  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["available","compacted"]
  
  - `compacted_at` (optional)
    Type: string, date-time
  
  - `item_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `results` (optional)
  Type: object
  
  Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.
  
  - `valid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `invalid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `disposable_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `unknown_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `catchall_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `unconfirmed` (optional)
  Type: object
  
  Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.
  
  - `excluded_count` (optional)
    Type: integer
    
    Addresses this run currently holds out of sends.
    
    minimum: 0
  
  - `sendable_count` (optional)
    Type: integer
    
    This run's unknown and catch-all addresses still in sends.
    
    minimum: 0
  
  - `pending` (optional)
    Type: boolean
    
    The run is still leaving its unconfirmed addresses out.
  
  - `kept_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `kept_at` (optional)
    Type: string, date-time
  
  - `can_include` (optional)
    Type: boolean
    
    Including this run's left-out addresses can be requested now.
  
  - `can_leave_out` (optional)
    Type: boolean
    
    Leaving this run's sendable unconfirmed addresses out can be requested now.
  
  - `include_blocked` (optional)
    Type: boolean
    
    Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.
  
  Additional properties: false

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `failure_code` (optional)
  Type: string

- `started_at` (optional)
  Type: string, date-time

- `completed_at` (optional)
  Type: string, date-time

- `next_action` (optional)
  Type: string

Additional properties: false

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: 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).

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/validation_operations/string/keep_unconfirmed' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations/string/keep_unconfirmed', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/validation_operations/string/keep_unconfirmed',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Leave a finished run's unknown and catch-all addresses out of sends

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

Responses:

- 200: Updated operation state

Content type: application/json

Type: object

Schema: [ValidationOperation](https://docs.nitrosend.com/api/schemas/validationoperation-3893a00de8.md)

- `operation_id` (required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

- `status` (required)
  Type: string
  
  enum: ["requested","quoted","held","executing","partially_committed","committed","released","needs_funding","failed"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `item_detail` (required)
  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["available","compacted"]
  
  - `compacted_at` (optional)
    Type: string, date-time
  
  - `item_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `results` (optional)
  Type: object
  
  Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.
  
  - `valid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `invalid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `disposable_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `unknown_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `catchall_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `unconfirmed` (optional)
  Type: object
  
  Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.
  
  - `excluded_count` (optional)
    Type: integer
    
    Addresses this run currently holds out of sends.
    
    minimum: 0
  
  - `sendable_count` (optional)
    Type: integer
    
    This run's unknown and catch-all addresses still in sends.
    
    minimum: 0
  
  - `pending` (optional)
    Type: boolean
    
    The run is still leaving its unconfirmed addresses out.
  
  - `kept_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `kept_at` (optional)
    Type: string, date-time
  
  - `can_include` (optional)
    Type: boolean
    
    Including this run's left-out addresses can be requested now.
  
  - `can_leave_out` (optional)
    Type: boolean
    
    Leaving this run's sendable unconfirmed addresses out can be requested now.
  
  - `include_blocked` (optional)
    Type: boolean
    
    Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.
  
  Additional properties: false

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `failure_code` (optional)
  Type: string

- `started_at` (optional)
  Type: string, date-time

- `completed_at` (optional)
  Type: string, date-time

- `next_action` (optional)
  Type: string

Additional properties: false

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The run is still finishing or its addresses are still being left out.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/validation_operations/string/exclude_unconfirmed' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations/string/exclude_unconfirmed', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/validation_operations/string/exclude_unconfirmed',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List per-candidate email validation results

`GET /v1/my/validation_operations/{id}/items`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Opaque operation_id returned by the create endpoint.
  Type: string
  
  minLength: 32
  
  maxLength: 64

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 30
  
  maximum: 100

Responses:

- 200: Paginated operation items

Content type: application/json

Type: array

Items:
  Reference: [ValidationOperationItem](https://docs.nitrosend.com/api/schemas/validationoperationitem-80942f06be.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/validation_operations/string/items?page=1&per=30' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/validation_operations/string/items?page=1&per=30', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/validation_operations/string/items?page=1&per=30',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List accessible accounts (paginated)

`GET /v1/my/accounts`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 100
  
  maximum: 100

Responses:

- 200: Accessible accounts

Content type: application/json

Type: array

Items:
  Reference: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/accounts?page=1&per=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/accounts?page=1&per=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/accounts?page=1&per=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List the selected manager account's client portfolio

`GET /v1/my/managed_accounts`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

- `q` (query, string, optional)
  Type: string
  
  maxLength: 120

- `status` (query, unknown, optional) - Use needs_setup to group preparing, awaiting owner, payment required, and payment issue rows.
  Type: unknown
  
  allOf:
    Reference: [ManagedAccountLifecycleStatusFilter](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatusfilter-5852c68708.md); Type: string
    
    enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended","needs_setup"]

- `sort` (query, string, optional)
  Type: string
  
  default: "created_at"
  
  enum: ["created_at","name","owner_email","status"]

- `direction` (query, string, optional)
  Type: string
  
  default: "desc"
  
  enum: ["asc","desc"]

Responses:

- 200: Bounded managed-client portfolio

Content type: application/json

Type: array

Items:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/managed_accounts?page=1&per=25&sort=created_at&direction=desc' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts?page=1&per=25&sort=created_at&direction=desc', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/managed_accounts?page=1&per=25&sort=created_at&direction=desc',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Provision a paid-required, client-owned account

`POST /v1/my/managed_accounts`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required) - Exact-request idempotency key; changed normalized input conflicts.
  Type: string
  
  minLength: 8
  
  maxLength: 255

Request body: application/json (required)

Type: object

Schema: [DashboardManagedAccountCreateRequest](https://docs.nitrosend.com/api/schemas/dashboardmanagedaccountcreaterequest-820244c8df.md)

- `managed_account` (required)
  Type: object
  
  - `owner_email` (required)
    Type: string, email
  
  - `owner_first_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `owner_last_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `account_name` (required)
    Type: string
    
    maxLength: 120

Responses:

- 200: Exact idempotent replay

Content type: application/json

Type: ManagedAccountProvisioningCreated

Schema: [ManagedAccountProvisioningCreated](https://docs.nitrosend.com/api/schemas/managedaccountprovisioningcreated-5c46bea353.md)

allOf:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

  Type: object
  
  - `idempotent_replay` (required)
    Type: boolean

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

Content type: application/json

Type: ManagedAccountProvisioningCreated

Schema: [ManagedAccountProvisioningCreated](https://docs.nitrosend.com/api/schemas/managedaccountprovisioningcreated-5c46bea353.md)

allOf:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

  Type: object
  
  - `idempotent_replay` (required)
    Type: boolean

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/managed_accounts' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "managed_account": {
    "owner_email": "user@example.com",
    "owner_first_name": "string",
    "owner_last_name": "string",
    "account_name": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "managed_account": {
    "owner_email": "user@example.com",
    "owner_first_name": "string",
    "owner_last_name": "string",
    "account_name": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "managed_account": {
    "owner_email": "user@example.com",
    "owner_first_name": "string",
    "owner_last_name": "string",
    "account_name": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/managed_accounts',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get one managed-client portfolio row

`GET /v1/my/managed_accounts/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Managed-client portfolio row

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/managed_accounts/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/managed_accounts/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


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

`POST /v1/my/managed_accounts/{id}/resend_invitation`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Updated portfolio row; no invitation capability is returned

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/managed_accounts/0/resend_invitation' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts/0/resend_invitation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/managed_accounts/0/resend_invitation',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Queue the first bounded owner invitation after client setup is ready

`POST /v1/my/managed_accounts/{id}/send_invitation`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Updated portfolio row; no invitation capability is returned

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/managed_accounts/0/send_invitation' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts/0/send_invitation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/managed_accounts/0/send_invitation',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Queue a cooldown-bound payment reminder to the owner

`POST /v1/my/managed_accounts/{id}/payment_reminder`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 204: Reminder accepted for delivery

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/managed_accounts/0/payment_reminder' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts/0/payment_reminder', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/managed_accounts/0/payment_reminder',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## End the selected manager's relationship with the client

`POST /v1/my/managed_accounts/{id}/release`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Ended managed-client relationship

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/managed_accounts/0/release' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/managed_accounts/0/release', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/managed_accounts/0/release',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List non-secret provisioning credential metadata

`GET /v1/my/account/provisioning_credentials`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Provisioning credential metadata

Content type: application/json

Type: array

Items:
  Reference: [AccountProvisioningCredential](https://docs.nitrosend.com/api/schemas/accountprovisioningcredential-a324087370.md); Type: object

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account/provisioning_credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/provisioning_credentials', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account/provisioning_credentials',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Issue a provisioning credential and reveal its secret once

`POST /v1/my/account/provisioning_credentials`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [AccountProvisioningCredentialCreateRequest](https://docs.nitrosend.com/api/schemas/accountprovisioningcredentialcreaterequest-485636e9e1.md)

- `credential` (required)
  Type: object
  
  - `name` (required)
    Type: string
    
    maxLength: 120
  
  - `scopes` (required)
    Type: array
    
    minItems: 1
    
    uniqueItems: true
    
    Items:
      Type: string
      
      enum: ["provision","manage"]
  
  - `expires_at` (optional)
    Type: string, date-time

Responses:

- 201: One-time credential result

Content type: application/json

Type: AccountProvisioningCredentialIssued

Schema: [AccountProvisioningCredentialIssued](https://docs.nitrosend.com/api/schemas/accountprovisioningcredentialissued-686c0a6700.md)

allOf:
  Reference: [AccountProvisioningCredential](https://docs.nitrosend.com/api/schemas/accountprovisioningcredential-a324087370.md); Type: object

  Type: object
  
  - `secret` (required)
    Type: string
    
    One-time nspk_live_ credential secret.
    
    writeOnly: true

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/account/provisioning_credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "credential": {
    "name": "string",
    "scopes": [
      "provision"
    ],
    "expires_at": "2024-01-15T09:30:00Z"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "credential": {
    "name": "string",
    "scopes": [
      "provision"
    ],
    "expires_at": "2024-01-15T09:30:00Z"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/account/provisioning_credentials', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "credential": {
    "name": "string",
    "scopes": [
      "provision"
    ],
    "expires_at": "2024-01-15T09:30:00Z"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/account/provisioning_credentials',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Revoke one manager-bound provisioning credential

`DELETE /v1/my/account/provisioning_credentials/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Revoked credential metadata

Content type: application/json

Type: object

Schema: [AccountProvisioningCredential](https://docs.nitrosend.com/api/schemas/accountprovisioningcredential-a324087370.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  maxLength: 120

- `scopes` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["provision","manage"]

- `secret_hint` (required)
  Type: string

- `expires_at` (required)
  Type: string, date-time

- `last_used_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `created_at` (required)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/account/provisioning_credentials/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/provisioning_credentials/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/account/provisioning_credentials/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Inspect a bounded owner consent capability

`POST /v1/managed_account_claims/inspect`

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

Schema: [ManagedAccountClaimRequest](https://docs.nitrosend.com/api/schemas/managedaccountclaimrequest-9a4b0bb9dd.md)

- `claim` (required)
  Type: object
  
  - `token` (required)
    Type: string
    
    writeOnly: true

Responses:

- 200: Bounded claim projection

Content type: application/json

Type: object

Schema: [ManagedAccountClaimInspection](https://docs.nitrosend.com/api/schemas/managedaccountclaiminspection-22c1590231.md)

- `manager` (required)
  Type: object
  
  - `name` (optional)
    Type: string; nullable

- `managed_account` (required)
  Type: object
  
  - `name` (optional)
    Type: string; nullable

- `owner_email` (required)
  Type: string
  
  Masked owner address

- `expires_at` (required)
  Type: string, date-time

- `authentication` (required)
  Type: string
  
  const: "login_required"

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

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/managed_account_claims/inspect' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "claim": {
    "token": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "claim": {
    "token": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/managed_account_claims/inspect', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "claim": {
    "token": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/managed_account_claims/inspect',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Record one-time consent for the exact authenticated owner

`POST /v1/managed_account_claims/complete`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [ManagedAccountClaimRequest](https://docs.nitrosend.com/api/schemas/managedaccountclaimrequest-9a4b0bb9dd.md)

- `claim` (required)
  Type: object
  
  - `token` (required)
    Type: string
    
    writeOnly: true

Responses:

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

Content type: application/json

Type: object

Schema: [ManagedAccountClaimCompletion](https://docs.nitrosend.com/api/schemas/managedaccountclaimcompletion-76dbe5b244.md)

- `claimed` (required)
  Type: boolean
  
  const: true

- `status` (required)
  Type: string
  
  The agency's management access. active on Setup mode does not mean paid; read payment_required.
  
  enum: ["payment_required","active","manager_disabled"]

- `payment_required` (required)
  Type: boolean
  
  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_setup` (required)
  Type: boolean
  
  The client account is on Setup mode.

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

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

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/managed_account_claims/complete' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "claim": {
    "token": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "claim": {
    "token": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/managed_account_claims/complete', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "claim": {
    "token": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/managed_account_claims/complete',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List managed clients using a manager-bound credential

`GET /v1/partner/managed_accounts`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Responses:

- 200: Managed-client portfolio

Content type: application/json

Type: array

Items:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/partner/managed_accounts' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/partner/managed_accounts',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Provision a paid-required client-owned account

`POST /v1/partner/managed_accounts`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `Idempotency-Key` (header, string, required) - Exact-request idempotency key; changed normalized input conflicts.
  Type: string
  
  minLength: 8
  
  maxLength: 255

Request body: application/json (required)

Type: object

Schema: [PartnerManagedAccountCreateRequest](https://docs.nitrosend.com/api/schemas/partnermanagedaccountcreaterequest-4c62de1c94.md)

- `managed_account` (required)
  Type: object
  
  - `external_ref` (required)
    Type: string
    
    maxLength: 128
  
  - `owner_email` (required)
    Type: string, email
  
  - `owner_first_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `owner_last_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `account_name` (required)
    Type: string
    
    maxLength: 120

Responses:

- 200: Exact idempotent replay

Content type: application/json

Type: ManagedAccountProvisioningCreated

Schema: [ManagedAccountProvisioningCreated](https://docs.nitrosend.com/api/schemas/managedaccountprovisioningcreated-5c46bea353.md)

allOf:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

  Type: object
  
  - `idempotent_replay` (required)
    Type: boolean

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

Content type: application/json

Type: ManagedAccountProvisioningCreated

Schema: [ManagedAccountProvisioningCreated](https://docs.nitrosend.com/api/schemas/managedaccountprovisioningcreated-5c46bea353.md)

allOf:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

  Type: object
  
  - `idempotent_replay` (required)
    Type: boolean

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/partner/managed_accounts' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "managed_account": {
    "external_ref": "string",
    "owner_email": "user@example.com",
    "owner_first_name": "string",
    "owner_last_name": "string",
    "account_name": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "managed_account": {
    "external_ref": "string",
    "owner_email": "user@example.com",
    "owner_first_name": "string",
    "owner_last_name": "string",
    "account_name": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "managed_account": {
    "external_ref": "string",
    "owner_email": "user@example.com",
    "owner_first_name": "string",
    "owner_last_name": "string",
    "account_name": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/partner/managed_accounts',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get one manager-scoped portfolio row

`GET /v1/partner/managed_accounts/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Managed-client portfolio row

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/partner/managed_accounts/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/partner/managed_accounts/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


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

`POST /v1/partner/managed_accounts/{id}/resend_invitation`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Updated portfolio row; no invitation capability is returned

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/partner/managed_accounts/0/resend_invitation' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts/0/resend_invitation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/partner/managed_accounts/0/resend_invitation',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Queue the first bounded owner invitation after client setup is ready

`POST /v1/partner/managed_accounts/{id}/send_invitation`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Updated portfolio row; no invitation capability is returned

Content type: application/json

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/partner/managed_accounts/0/send_invitation' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts/0/send_invitation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/partner/managed_accounts/0/send_invitation',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List non-secret agent credential metadata for one managed client

`GET /v1/partner/managed_accounts/{provisioning_id}/credentials`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `provisioning_id` (path, integer, required) - Manager-scoped provisioning row id.
  Type: integer

Responses:

- 200: Agent credential metadata; plaintext secrets are never listed

Content type: application/json

Type: array

Items:
  Reference: [AccountManagementCredential](https://docs.nitrosend.com/api/schemas/accountmanagementcredential-62a442ea85.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Issue one grant- and Brand-pinned agent credential

`POST /v1/partner/managed_accounts/{provisioning_id}/credentials`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `provisioning_id` (path, integer, required) - Manager-scoped provisioning row id.
  Type: integer

Request body: application/json (required)

Type: object

Schema: [AccountManagementCredentialCreateRequest](https://docs.nitrosend.com/api/schemas/accountmanagementcredentialcreaterequest-1f48d1e92b.md)

- `credential` (required)
  Type: object
  
  - `name` (required)
    Type: string
    
    maxLength: 120
  
  - `brand_sid` (optional)
    Type: string
    
    Defaults to the managed Account's default Brand.
  
  - `expires_at` (optional)
    Type: string, date-time
    
    Defaults to 90 days and cannot exceed one year.

Responses:

- 201: One-time credential result; the secret cannot be recovered

Content type: application/json

Type: AccountManagementCredentialIssued

Schema: [AccountManagementCredentialIssued](https://docs.nitrosend.com/api/schemas/accountmanagementcredentialissued-ccc873a72c.md)

allOf:
  Reference: [AccountManagementCredential](https://docs.nitrosend.com/api/schemas/accountmanagementcredential-62a442ea85.md); Type: object

  Type: object
  
  - `secret` (required)
    Type: string
    
    One-time nsmc_live_ credential secret.
    
    writeOnly: true

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Request conflicts with durable lifecycle or idempotency state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "credential": {
    "name": "string",
    "brand_sid": "string",
    "expires_at": "2024-01-15T09:30:00Z"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "credential": {
    "name": "string",
    "brand_sid": "string",
    "expires_at": "2024-01-15T09:30:00Z"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "credential": {
    "name": "string",
    "brand_sid": "string",
    "expires_at": "2024-01-15T09:30:00Z"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Revoke one agent credential immediately

`DELETE /v1/partner/managed_accounts/{provisioning_id}/credentials/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "PartnerProvisioningCredential": []
  }
]
```

- PartnerProvisioningCredential: http (bearer). Manager-account provisioning credential revealed once at issuance.

Parameters:

- `provisioning_id` (path, integer, required) - Manager-scoped provisioning row id.
  Type: integer

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Revoked credential metadata

Content type: application/json

Type: object

Schema: [AccountManagementCredential](https://docs.nitrosend.com/api/schemas/accountmanagementcredential-62a442ea85.md)

- `id` (required)
  Type: integer

- `account_management_grant_id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  maxLength: 120

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `secret_hint` (required)
  Type: string

- `expires_at` (required)
  Type: string, date-time

- `last_used_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `created_at` (required)
  Type: string, date-time

- `brand` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `sid` (required)
    Type: string
  
  - `name` (required)
    Type: string

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/partner/managed_accounts/0/credentials/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get the current account's pending or active management grant

`GET /v1/my/account/management_grant`

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

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Current management grant

Content type: application/json

Type: object

Schema: [AccountManagementGrant](https://docs.nitrosend.com/api/schemas/accountmanagementgrant-d8259a8074.md)

- `id` (required)
  Type: integer

- `status` (required)
  Type: string
  
  enum: ["pending","active","revoked","released"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `manager_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (optional)
    Type: string; nullable

- `requested_at` (required)
  Type: string, date-time

- `activated_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `released_at` (optional)
  Type: string, date-time; nullable

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account/management_grant' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/management_grant', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account/management_grant',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Reconcile a consented, paid managed-account grant

`POST /v1/my/account/management_grant/confirm`

This endpoint cannot record owner consent or bypass paid activation.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [AccountManagementGrantCommand](https://docs.nitrosend.com/api/schemas/accountmanagementgrantcommand-4ae97ecfc8.md)

- `management_grant_id` (required)
  Type: integer
  
  Exact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.

Responses:

- 200: Active management grant

Content type: application/json

Type: object

Schema: [AccountManagementGrant](https://docs.nitrosend.com/api/schemas/accountmanagementgrant-d8259a8074.md)

- `id` (required)
  Type: integer

- `status` (required)
  Type: string
  
  enum: ["pending","active","revoked","released"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `manager_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (optional)
    Type: string; nullable

- `requested_at` (required)
  Type: string, date-time

- `activated_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `released_at` (optional)
  Type: string, date-time; nullable

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The grant cannot transition from its current state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/account/management_grant/confirm' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "management_grant_id": 0
}'
```

### JavaScript

```javascript
const body = `{
  "management_grant_id": 0
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/account/management_grant/confirm', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "management_grant_id": 0
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/account/management_grant/confirm',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Revoke an exact pending or active management grant

`POST /v1/my/account/management_grant/revoke`

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

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [AccountManagementGrantCommand](https://docs.nitrosend.com/api/schemas/accountmanagementgrantcommand-4ae97ecfc8.md)

- `management_grant_id` (required)
  Type: integer
  
  Exact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.

Responses:

- 200: Revoked management grant

Content type: application/json

Type: object

Schema: [AccountManagementGrant](https://docs.nitrosend.com/api/schemas/accountmanagementgrant-d8259a8074.md)

- `id` (required)
  Type: integer

- `status` (required)
  Type: string
  
  enum: ["pending","active","revoked","released"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `manager_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (optional)
    Type: string; nullable

- `requested_at` (required)
  Type: string, date-time

- `activated_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `released_at` (optional)
  Type: string, date-time; nullable

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The grant cannot transition from its current state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/account/management_grant/revoke' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "management_grant_id": 0
}'
```

### JavaScript

```javascript
const body = `{
  "management_grant_id": 0
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/account/management_grant/revoke', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "management_grant_id": 0
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/account/management_grant/revoke',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get team metadata for the current account

`GET /v1/my/account/team`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Team metadata

Content type: application/json

Type: object

Schema: [AccountTeam](https://docs.nitrosend.com/api/schemas/accountteam-f67c1a5055.md)

- `account` (optional)
  Reference: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md); Type: object

- `memberships` (optional)
  Type: array
  
  Items:
    Reference: [AccountMembership](https://docs.nitrosend.com/api/schemas/accountmembership-1cc598e779.md); Type: object

- `invites` (optional)
  Type: array
  
  Items:
    Reference: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md); Type: object

- `accessible_accounts` (optional)
  Type: array
  
  Items:
    Reference: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account/team' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/team', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account/team',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## How far one send to an audience gets on the current plan

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `audience` (query, integer, required) - Number of recipients of one full send
  Type: integer
  
  minimum: 1

Responses:

- 200: Reach on the current plan and the recommended plan

Content type: application/json

Type: object

Schema: [AudienceReach](https://docs.nitrosend.com/api/schemas/audiencereach-106eff5b94.md)

- `audience` (required)
  Type: integer

- `cohort` (required)
  Type: string
  
  The account's deliverability cohort the daily caps are read at

- `current` (optional)
  Type: unknown; nullable
  
  The current plan; null when the account has no subscription
  
  allOf:
    Reference: [AudienceReachFit](https://docs.nitrosend.com/api/schemas/audiencereachfit-d5771ef0b5.md); Type: object

- `recommended` (optional)
  Type: unknown; nullable
  
  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
  
  allOf:
    Reference: [AudienceReachFit](https://docs.nitrosend.com/api/schemas/audiencereachfit-d5771ef0b5.md); Type: object

- `covered` (required)
  Type: boolean
  
  Whether the current plan covers a full send

- `summary` (optional)
  Type: string; nullable
  
  The one sentence every surface shows; null when covered

- 422: audience is not a positive whole number (error_code audience_invalid)

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account/reach?audience=1' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/reach?audience=1', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account/reach?audience=1',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List account memberships (paginated)

`GET /v1/my/account/memberships`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 100
  
  maximum: 100

Responses:

- 200: Memberships

Content type: application/json

Type: array

Items:
  Reference: [AccountMembership](https://docs.nitrosend.com/api/schemas/accountmembership-1cc598e779.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account/memberships?page=1&per=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/memberships?page=1&per=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account/memberships?page=1&per=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Remove a membership

`DELETE /v1/my/account/memberships/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Removed membership

Content type: application/json

Type: object

Schema: [AccountMembership](https://docs.nitrosend.com/api/schemas/accountmembership-1cc598e779.md)

- `id` (optional)
  Type: integer

- `role` (optional)
  Type: string
  
  enum: ["member","admin","owner"]

- `user_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `name` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/account/memberships/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/memberships/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/account/memberships/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a membership role

`PATCH /v1/my/account/memberships/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `role` (optional)
  Type: string
  
  enum: ["member","admin"]

Responses:

- 200: Updated membership

Content type: application/json

Type: object

Schema: [AccountMembership](https://docs.nitrosend.com/api/schemas/accountmembership-1cc598e779.md)

- `id` (optional)
  Type: integer

- `role` (optional)
  Type: string
  
  enum: ["member","admin","owner"]

- `user_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `name` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/account/memberships/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "role": "member"
}'
```

### JavaScript

```javascript
const body = `{
  "role": "member"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/account/memberships/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "role": "member"
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/account/memberships/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Download an account invoice

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Original invoice PDF

Content type: application/pdf

Type: string, binary

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

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

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 500: The invoice document could not be retrieved

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/invoices/0/download' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/invoices/0/download', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/invoices/0/download',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Ask the Nitrosend team about Enterprise

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json

Type: object

Schema: [EnterpriseRequestInput](https://docs.nitrosend.com/api/schemas/enterpriserequestinput-bf27cf7003.md)

- `monthly_emails` (optional)
  Type: unknown
  
  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.
  
  oneOf:
    Type: integer
    
    minimum: 0
    
    maximum: 1000000000
  
    Type: string
    
    pattern: "^[0-9]{1,10}$"
  
    Type: null

- `needs` (optional)
  Type: array; nullable
  
  maxItems: 6
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["volume_pricing","dedicated_ip","seats_or_domains","security_review","invoicing","migration"]

- `message` (optional)
  Type: string; nullable
  
  maxLength: 2000

Additional properties: false

Responses:

- 200: This member already sent a request today; the receipt is for that request

Content type: application/json

Type: object

Schema: [EnterpriseRequestReceipt](https://docs.nitrosend.com/api/schemas/enterpriserequestreceipt-586909efa0.md)

- `received` (required)
  Type: boolean
  
  const: true

- `replayed` (required)
  Type: boolean
  
  True when this is the member's request from earlier today.

- `request` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `received_at` (required)
    Type: string, date-time
  
  - `requester_email` (required)
    Type: string, email
    
    Where the team will reply.

- 201: Request received

Content type: application/json

Type: object

Schema: [EnterpriseRequestReceipt](https://docs.nitrosend.com/api/schemas/enterpriserequestreceipt-586909efa0.md)

- `received` (required)
  Type: boolean
  
  const: true

- `replayed` (required)
  Type: boolean
  
  True when this is the member's request from earlier today.

- `request` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `received_at` (required)
    Type: string, date-time
  
  - `requester_email` (required)
    Type: string, email
    
    Where the team will reply.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: A field has the wrong shape or is out of range (error_code enterprise_request_invalid, with validation_errors per field).

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 503: The request could not be sent to the team, so it was not kept (error_code enterprise_request_unrecorded); email contact@nitrosend.com instead.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/enterprise_requests' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "monthly_emails": 0,
  "needs": [
    "volume_pricing"
  ],
  "message": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "monthly_emails": 0,
  "needs": [
    "volume_pricing"
  ],
  "message": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/enterprise_requests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "monthly_emails": 0,
  "needs": [
    "volume_pricing"
  ],
  "message": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/enterprise_requests',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Read the current subscription

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: The current subscription, or null when the account has none

Content type: application/json

Type: unknown

anyOf:
  Reference: [Subscription](https://docs.nitrosend.com/api/schemas/subscription-4999c6c6c7.md); Type: object

  Reference: [DelegatedSubscription](https://docs.nitrosend.com/api/schemas/delegatedsubscription-e2844fb27a.md); Type: 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.

  Type: null

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/subscription', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/subscription',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a subscription

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [SubscriptionCreateRequest](https://docs.nitrosend.com/api/schemas/subscriptioncreaterequest-d5e60ab175.md)

- `plan_id` (required)
  Type: integer

- `stripe_token` (optional)
  Type: string; nullable
  
  Stripe card token for paid-plan creation.

- `coupon_code` (optional)
  Type: string; nullable
  
  Customer-entered Stripe promotion code or coupon ID. Refused on an agency operator's purchase for a client account.

Responses:

- 201: Subscription created

Content type: application/json

Type: unknown

anyOf:
  Reference: [Subscription](https://docs.nitrosend.com/api/schemas/subscription-4999c6c6c7.md); Type: object

  Reference: [DelegatedSubscription](https://docs.nitrosend.com/api/schemas/delegatedsubscription-e2844fb27a.md); Type: 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.

- 403: 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).

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: The plan is not available to this account, including Free for an agency or a client account an agency created.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: 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).

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: 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.

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "plan_id": 0,
  "stripe_token": "string",
  "coupon_code": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "plan_id": 0,
  "stripe_token": "string",
  "coupon_code": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/subscription', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "plan_id": 0,
  "stripe_token": "string",
  "coupon_code": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/subscription',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Cancel the current paid plan at its period end

`DELETE /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Cancellation scheduled

Content type: application/json

Type: object

Schema: [Subscription](https://docs.nitrosend.com/api/schemas/subscription-4999c6c6c7.md)

- `id` (optional)
  Type: integer

- `plan_id` (optional)
  Type: integer

- `plan_name` (optional)
  Type: string; nullable
  
  Current package name. Historical purchase labels are retained in billing records.

- `billing_provider` (optional)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `source_billing_provider` (optional)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `billing_migration_required` (optional)
  Type: boolean

- `manage_url` (optional)
  Type: string, uri; nullable

- `spend_cap_monthly_cents` (optional)
  Type: integer; nullable
  
  Merchant-selected monthly cap for metered usage charges.
  
  minimum: 0

- `shopify_usage_metered` (optional)
  Type: boolean
  
  Whether the active Shopify plan has at least one configured usage meter.

- `status` (optional)
  Type: string
  
  enum: ["pending","active","inactive","canceled","free_tier"]

- `interval` (optional)
  Type: string
  
  enum: ["month","year","week","day"]

- `currency` (optional)
  Type: string

- `subtotal_cents` (optional)
  Type: integer

- `tax_cents` (optional)
  Type: integer

- `total_cents` (optional)
  Type: integer

- `base_price_cents` (optional)
  Type: integer

- `discount_cents` (optional)
  Type: integer
  
  Per-period Stripe discount in cents (0 when none).

- `next_payment_cents` (optional)
  Type: integer
  
  Amount billed next period

- `discount_end_at` (optional)
  Type: string, date-time; nullable
  
  When the discount stops (null for forever/once or no discount).

- `activated` (optional)
  Type: boolean

- `entitlements` (optional)
  Reference: [BillingEntitlements](https://docs.nitrosend.com/api/schemas/billingentitlements-6434d07335.md); Type: object

- 403: Billing for this account is managed by another provider (error_code manage_on_shopify or billing_provider_unavailable)

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: There is no paid plan this account can cancel here.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: 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.").

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/subscription', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/subscription',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Change the current subscription plan

`PUT /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [SubscriptionChangeRequest](https://docs.nitrosend.com/api/schemas/subscriptionchangerequest-9820d6506c.md)

- `plan_id` (required)
  Type: integer

- `coupon_code` (optional)
  Type: string; nullable
  
  Customer-entered Stripe promotion code or coupon ID.

Responses:

- 200: Subscription updated

Content type: application/json

Type: object

Schema: [Subscription](https://docs.nitrosend.com/api/schemas/subscription-4999c6c6c7.md)

- `id` (optional)
  Type: integer

- `plan_id` (optional)
  Type: integer

- `plan_name` (optional)
  Type: string; nullable
  
  Current package name. Historical purchase labels are retained in billing records.

- `billing_provider` (optional)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `source_billing_provider` (optional)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `billing_migration_required` (optional)
  Type: boolean

- `manage_url` (optional)
  Type: string, uri; nullable

- `spend_cap_monthly_cents` (optional)
  Type: integer; nullable
  
  Merchant-selected monthly cap for metered usage charges.
  
  minimum: 0

- `shopify_usage_metered` (optional)
  Type: boolean
  
  Whether the active Shopify plan has at least one configured usage meter.

- `status` (optional)
  Type: string
  
  enum: ["pending","active","inactive","canceled","free_tier"]

- `interval` (optional)
  Type: string
  
  enum: ["month","year","week","day"]

- `currency` (optional)
  Type: string

- `subtotal_cents` (optional)
  Type: integer

- `tax_cents` (optional)
  Type: integer

- `total_cents` (optional)
  Type: integer

- `base_price_cents` (optional)
  Type: integer

- `discount_cents` (optional)
  Type: integer
  
  Per-period Stripe discount in cents (0 when none).

- `next_payment_cents` (optional)
  Type: integer
  
  Amount billed next period

- `discount_end_at` (optional)
  Type: string, date-time; nullable
  
  When the discount stops (null for forever/once or no discount).

- `activated` (optional)
  Type: boolean

- `entitlements` (optional)
  Reference: [BillingEntitlements](https://docs.nitrosend.com/api/schemas/billingentitlements-6434d07335.md); Type: object

- 400: The change cannot be applied, including any change from Setup mode (message "Choose a plan to leave Setup mode.").

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: The plan is not available to this account, including Free for an agency or a client account an agency created.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer).

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PUT 'https://api.nitrosend.com/v1/my/subscription/change' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "plan_id": 0,
  "coupon_code": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "plan_id": 0,
  "coupon_code": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/subscription/change', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "plan_id": 0,
  "coupon_code": "string"
}'''

response = requests.put(
    'https://api.nitrosend.com/v1/my/subscription/change',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Start a subscription checkout

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, optional) - Optional stable retry key. The server also reuses an open same-plan checkout.
  Type: string
  
  maxLength: 128

Request body: application/json (required)

Type: object

- `plan_id` (required)
  Type: integer

- `product_key` (optional)
  Type: string
  
  default: "base_plan"
  
  enum: ["base_plan","brand_capacity","domain_capacity","seat_capacity","footer_removal"]

- `quantity` (optional)
  Type: integer
  
  Units for a quantity-based offer returned by features. Other offers require one. Bound to the idempotency key.
  
  default: 1
  
  minimum: 1
  
  maximum: 10000

- `idempotency_key` (optional)
  Type: string
  
  Optional body form of Idempotency-Key for compatibility.
  
  maxLength: 128

- `new_subscription` (optional)
  Type: boolean
  
  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.
  
  default: false

- `coupon_code` (optional)
  Type: string
  
  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.

Responses:

- 200: Subscription changed without external approval

Content type: application/json

Type: object

Additional properties: true

- 201: Provider-hosted checkout created

Content type: application/json

Type: object

Additional properties: true

- 403: 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)

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Requested plan is not available, including Free for an agency or a client account an agency created

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Another checkout is pending, the idempotency key conflicts, or (with new_subscription) the account already has another paid plan (error_code plan_checkout_pending)

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Shopify rejected the requested billing terms, or the coupon is invalid or can't apply (validation_errors.coupon_code)

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: The billing provider could not be reached

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/subscription/checkout' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "plan_id": 0,
  "product_key": "base_plan",
  "quantity": 1,
  "idempotency_key": "string",
  "new_subscription": false,
  "coupon_code": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "plan_id": 0,
  "product_key": "base_plan",
  "quantity": 1,
  "idempotency_key": "string",
  "new_subscription": false,
  "coupon_code": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/subscription/checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "plan_id": 0,
  "product_key": "base_plan",
  "quantity": 1,
  "idempotency_key": "string",
  "new_subscription": false,
  "coupon_code": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/subscription/checkout',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Reconcile and read a plan purchase

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `product_key` (query, string, optional)
  Type: string
  
  default: "base_plan"
  
  enum: ["base_plan"]

- `purchase_id` (query, integer, optional)
  Type: integer

Responses:

- 200: Reconciled plan purchase status

Content type: application/json

Type: object

- `purchase_id` (optional)
  Type: integer; nullable

- `subscription_id` (optional)
  Type: integer; nullable

- `has_subscription` (required)
  Type: boolean

- `status` (optional)
  Type: string; nullable

- `activated` (required)
  Type: boolean

- `plan_name` (optional)
  Type: string; nullable

- `provider_status` (optional)
  Type: string; nullable

- `checkout_url` (optional)
  Type: string, uri; nullable

- `approval` (optional)
  Type: object; nullable
  
  Additional properties: true

- `billing_provider` (required)
  Type: string

- `billing_route` (required)
  Type: object
  
  Additional properties: true

- `manage_url` (optional)
  Type: string, uri; nullable

- `entitlements` (optional)
  Type: object; nullable
  
  Additional properties: true

- `next_action` (optional)
  Type: string

- 404: Requested plan purchase was not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: Provider state could not be verified

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/subscription/checkout_status?product_key=base_plan' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/subscription/checkout_status?product_key=base_plan', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/subscription/checkout_status?product_key=base_plan',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Read the current prepaid funding projection and available instruments

`GET /v1/my/billing/funding`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Current prepaid funding status

Content type: application/json

Type: object

Schema: [FundingStatus](https://docs.nitrosend.com/api/schemas/fundingstatus-b79b1e333b.md)

- `state` (required)
  Type: string

- `applies_to` (required)
  Type: string
  
  enum: ["prepaid_features"]

- `subscription_gate` (required)
  Type: boolean

- `currency` (required)
  Type: string

- `available_cents` (required)
  Type: integer

- `reserved_cents` (required)
  Type: integer

- `deficit_cents` (required)
  Type: integer

- `purchase` (required)
  Reference: [FundingPurchaseCapability](https://docs.nitrosend.com/api/schemas/fundingpurchasecapability-9fb3ffa1d8.md); Type: object

- `pending_purchase` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md); Type: object

Additional properties: true

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/billing/funding' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/billing/funding', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/billing/funding',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Start an add-funds purchase with an optional hosted instrument

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required)
  Type: string
  
  maxLength: 128

Request body: application/json (required)

Type: object

Schema: [FundingPurchaseCreateRequest](https://docs.nitrosend.com/api/schemas/fundingpurchasecreaterequest-75107d5668.md)

- `amount_cents` (required)
  Type: integer
  
  Integer service value in minor currency units.
  
  minimum: 1

- `currency` (optional)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `instrument` (optional)
  Type: string
  
  Optional hosted funding instrument. Omit to use the account default.
  
  enum: ["stripe_checkout","shopify_one_time"]

- `paid_action_intent_id` (optional)
  Type: string; nullable
  
  Optional opaque continuation bound to this funding purchase.

Additional properties: false

Responses:

- 200: Existing idempotent funding purchase

Content type: application/json

Type: object

Schema: [FundingPurchaseResponse](https://docs.nitrosend.com/api/schemas/fundingpurchaseresponse-f77d32410d.md)

- `purchase` (required)
  Reference: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md); Type: object

- `funding` (required)
  Reference: [FundingStatus](https://docs.nitrosend.com/api/schemas/fundingstatus-b79b1e333b.md); Type: object

Additional properties: false

- 201: Funding purchase created

Content type: application/json

Type: object

Schema: [FundingPurchaseResponse](https://docs.nitrosend.com/api/schemas/fundingpurchaseresponse-f77d32410d.md)

- `purchase` (required)
  Reference: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md); Type: object

- `funding` (required)
  Reference: [FundingStatus](https://docs.nitrosend.com/api/schemas/fundingstatus-b79b1e333b.md); Type: object

Additional properties: false

- 409: Idempotency key was used for different funding input

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Amount or selected funding instrument is unavailable

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/billing/funding/purchases' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "amount_cents": 1,
  "currency": "string",
  "instrument": "stripe_checkout",
  "paid_action_intent_id": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "amount_cents": 1,
  "currency": "string",
  "instrument": "stripe_checkout",
  "paid_action_intent_id": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/billing/funding/purchases', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "amount_cents": 1,
  "currency": "string",
  "instrument": "stripe_checkout",
  "paid_action_intent_id": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/billing/funding/purchases',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Read an account-scoped funding purchase

`GET /v1/my/billing/funding/purchases/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Local purchase ID or opaque Stripe Checkout Session ID
  Type: string

Responses:

- 200: Funding purchase status

Content type: application/json

Type: object

Schema: [FundingPurchaseResponse](https://docs.nitrosend.com/api/schemas/fundingpurchaseresponse-f77d32410d.md)

- `purchase` (required)
  Reference: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md); Type: object

- `funding` (required)
  Reference: [FundingStatus](https://docs.nitrosend.com/api/schemas/fundingstatus-b79b1e333b.md); Type: object

Additional properties: false

- 404: Funding purchase not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/billing/funding/purchases/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/billing/funding/purchases/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/billing/funding/purchases/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Preview a promotion code or coupon for a subscription plan

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [SubscriptionCouponPreviewRequest](https://docs.nitrosend.com/api/schemas/subscriptioncouponpreviewrequest-bdb93fff78.md)

- `plan_id` (required)
  Type: integer

- `coupon_code` (required)
  Type: string
  
  Customer-entered Stripe promotion code or coupon ID.

Responses:

- 200: Coupon preview

Content type: application/json

Type: object

Schema: [SubscriptionCouponPreview](https://docs.nitrosend.com/api/schemas/subscriptioncouponpreview-f8bacf6139.md)

- `code` (required)
  Type: string

- `discount_label` (required)
  Type: string

- `discount_cents` (required)
  Type: integer

- `subtotal_cents` (required)
  Type: integer

- `tax_cents` (required)
  Type: integer

- `total_cents` (required)
  Type: integer

- `total_after_discount_cents` (required)
  Type: integer

- `currency` (required)
  Type: string

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/subscription/coupon_preview' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "plan_id": 0,
  "coupon_code": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "plan_id": 0,
  "coupon_code": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/subscription/coupon_preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "plan_id": 0,
  "coupon_code": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/subscription/coupon_preview',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List account invites (paginated)

`GET /v1/my/account/invites`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 100
  
  maximum: 100

Responses:

- 200: Invites

Content type: application/json

Type: array

Items:
  Reference: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/account/invites?page=1&per=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites?page=1&per=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/account/invites?page=1&per=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create an account invite

`POST /v1/my/account/invites`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `email` (required)
  Type: string, email

- `role` (optional)
  Type: string
  
  enum: ["member","admin"]

Responses:

- 201: Created invite

Content type: application/json

Type: object

Schema: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `role` (optional)
  Type: string
  
  enum: ["member","admin"]

- `token` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["pending","accepted","revoked","expired"]

- `accepted_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `expires_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/account/invites' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "role": "member"
}'
```

### JavaScript

```javascript
const body = `{
  "email": "user@example.com",
  "role": "member"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/account/invites', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "email": "user@example.com",
  "role": "member"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/account/invites',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Revoke an invite

`DELETE /v1/my/account/invites/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Revoked invite

Content type: application/json

Type: object

Schema: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `role` (optional)
  Type: string
  
  enum: ["member","admin"]

- `token` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["pending","accepted","revoked","expired"]

- `accepted_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `expires_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/account/invites/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/account/invites/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Accept an invite token

`POST /v1/my/account/invites/{id}/accept`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required)
  Type: string

Responses:

- 200: Accepted invite

Content type: application/json

Type: object

Schema: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `role` (optional)
  Type: string
  
  enum: ["member","admin"]

- `token` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["pending","accepted","revoked","expired"]

- `accepted_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `expires_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/account/invites/string/accept' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites/string/accept', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/account/invites/string/accept',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List contacts (paginated)

`GET /v1/my/contacts`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 50
  
  maximum: 100

- `search` (query, string, optional) - Full-text search across name, email, phone
  Type: string

- `filters` (query, SegmentFilterExpression, optional) - 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.

  Type: SegmentFilterExpression
  
  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.
  
  
  Schema: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md)
  
  oneOf:
    Reference: [SegmentFilters](https://docs.nitrosend.com/api/schemas/segmentfilters-0ad9c0a44c.md); Type: 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.
    
  
    Reference: [FlatAndSegmentFilterExpression](https://docs.nitrosend.com/api/schemas/flatandsegmentfilterexpression-2ec627072b.md); Type: object
  
    Reference: [BooleanSegmentFilterGroup](https://docs.nitrosend.com/api/schemas/booleansegmentfiltergroup-8364897715.md); Type: object

- `list_id` (query, integer, optional) - Legacy shortcut for a `contact_list in [id]` filter.
  Type: integer

- `tag` (query, string, optional) - 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`.

  Type: string

- `sort` (query, string, optional) - 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.

  Type: string
  
  enum: ["created_at","emails_sent","unique_opens","clicks","open_rate","click_rate","last_opened_at","last_clicked_at","rating"]

- `direction` (query, string, optional) - Sort direction. Only applies when `sort` is set.
  Type: string
  
  default: "desc"
  
  enum: ["asc","desc"]

Responses:

- 200: Paginated contacts

Content type: application/json

Type: array

Items:
  Reference: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md); Type: object

- 503: 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.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/contacts?page=1&limit=50&direction=desc' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts?page=1&limit=50&direction=desc', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/contacts?page=1&limit=50&direction=desc',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a contact

`POST /v1/my/contacts`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `first_name` (optional)
  Type: string

- `last_name` (optional)
  Type: string

- `email` (optional)
  Type: string, 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.

- `phone` (optional)
  Type: string
  
  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}.

- `source` (optional)
  Type: string

- `country_code` (optional)
  Type: string

- `opt_in` (optional)
  Type: boolean; nullable
  
  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_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `channels_attributes` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `kind` (optional)
      Type: string
      
      enum: ["email","phone"]
    
    - `value` (optional)
      Type: string
    
    - `subscribed` (optional)
      Type: boolean

Responses:

- 200: 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.


Content type: application/json

Type: object

Schema: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `uuid` (optional)
  Type: string, uuid

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `source` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `flag_emoji` (optional)
  Type: string; nullable
  
  Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `subscribed_phone` (optional)
  Type: boolean

- `subscribed_email` (optional)
  Type: boolean

- `email` (optional)
  Type: string, email; nullable
  
  Convenience value for the preferred email channel. Full channel detail remains in channels[].

- `subscribed` (optional)
  Type: object
  
  Denormalized subscription summary by channel family.
  
  - `email` (optional)
    Type: boolean
  
  - `phone` (optional)
    Type: boolean

- `verification_status` (optional)
  Type: string
  
  enum: ["verified","suppressed","unverified"]

- `verification_result` (optional)
  Type: string; nullable
  
  Newest list-verification result for the contact's email; null when never checked.
  
  enum: ["valid","invalid","disposable","catchall","unknown",null]

- `enrichment_status` (optional)
  Type: string
  
  enum: ["enriched","not_enriched"]

- `mailbox_provider` (optional)
  Type: string
  
  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.
  
  
  enum: ["gmail","apple","outlook","corporate","unknown"]

- `list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `last_interacted_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `engagement` (optional)
  Type: object; nullable
  
  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.
  
  
  - `rating` (optional)
    Type: string
    
    Five-tier engagement rating based on recency of opens and clicks.
    
    enum: ["engaged","warm","cooling","dormant","never"]
  
  - `emails_sent` (optional)
    Type: integer
  
  - `unique_opens` (optional)
    Type: integer
  
  - `clicks` (optional)
    Type: integer
  
  - `open_rate` (optional)
    Type: number, float; nullable
  
  - `click_rate` (optional)
    Type: number, float; nullable
  
  - `last_opened_at` (optional)
    Type: string, date-time; nullable
  
  - `last_clicked_at` (optional)
    Type: string, date-time; nullable

- `channels` (optional)
  Type: array
  
  Items:
    Reference: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md); Type: object

- 201: Contact created

Content type: application/json

Type: object

Schema: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `uuid` (optional)
  Type: string, uuid

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `source` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `flag_emoji` (optional)
  Type: string; nullable
  
  Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `subscribed_phone` (optional)
  Type: boolean

- `subscribed_email` (optional)
  Type: boolean

- `email` (optional)
  Type: string, email; nullable
  
  Convenience value for the preferred email channel. Full channel detail remains in channels[].

- `subscribed` (optional)
  Type: object
  
  Denormalized subscription summary by channel family.
  
  - `email` (optional)
    Type: boolean
  
  - `phone` (optional)
    Type: boolean

- `verification_status` (optional)
  Type: string
  
  enum: ["verified","suppressed","unverified"]

- `verification_result` (optional)
  Type: string; nullable
  
  Newest list-verification result for the contact's email; null when never checked.
  
  enum: ["valid","invalid","disposable","catchall","unknown",null]

- `enrichment_status` (optional)
  Type: string
  
  enum: ["enriched","not_enriched"]

- `mailbox_provider` (optional)
  Type: string
  
  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.
  
  
  enum: ["gmail","apple","outlook","corporate","unknown"]

- `list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `last_interacted_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `engagement` (optional)
  Type: object; nullable
  
  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.
  
  
  - `rating` (optional)
    Type: string
    
    Five-tier engagement rating based on recency of opens and clicks.
    
    enum: ["engaged","warm","cooling","dormant","never"]
  
  - `emails_sent` (optional)
    Type: integer
  
  - `unique_opens` (optional)
    Type: integer
  
  - `clicks` (optional)
    Type: integer
  
  - `open_rate` (optional)
    Type: number, float; nullable
  
  - `click_rate` (optional)
    Type: number, float; nullable
  
  - `last_opened_at` (optional)
    Type: string, date-time; nullable
  
  - `last_clicked_at` (optional)
    Type: string, date-time; nullable

- `channels` (optional)
  Type: array
  
  Items:
    Reference: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md); Type: object

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/contacts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "opt_in": true,
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "kind": "email",
      "value": "string",
      "subscribed": true
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "opt_in": true,
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "kind": "email",
      "value": "string",
      "subscribed": true
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "opt_in": true,
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "kind": "email",
      "value": "string",
      "subscribed": true
    }
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/contacts',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Apply an action to selected contacts

`POST /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`.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `action_type` (required)
  Type: string
  
  enum: ["add_to_list","remove_from_list","delete","unsubscribe_email"]

- `ids` (optional)
  Type: array
  
  Required unless `match` is sent. Send one of `ids` or `match`.
  
  Items:
    Type: integer

- `list_id` (optional)
  Type: integer
  
  Required for add_to_list and remove_from_list.

- `match` (optional)
  Type: object
  
  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.
  
  - `search` (optional)
    Type: string
  
  - `filters` (optional)
    Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
    
    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.
    
  
  - `list_id` (optional)
    Type: integer
  
  - `tag` (optional)
    Type: string
  
  - `source` (optional)
    Type: string
  
  Additional properties: false

- `dry_run` (optional)
  Type: boolean
  
  Delete only. Returns the count and confirmation wording without deleting.

- `selection_digest` (optional)
  Type: string
  
  Delete with `match` only, and required there. The `selection_digest` from the dry run being confirmed.

Responses:

- 200: Action completed, or a delete dry run

Content type: application/json

Type: object

- `affected` (optional)
  Type: integer

- `action` (required)
  Type: string

- `list_id` (optional)
  Type: integer

- `status` (optional)
  Type: string
  
  enum: ["done"]

- `dry_run` (optional)
  Type: boolean

- `kept` (optional)
  Type: integer
  
  Delete only. Contacts kept because they are still in use, such as in email conversations or an email verification that is still running.

- `contact_count` (optional)
  Type: integer
  
  Delete only. Contacts selected.

- `selection_digest` (optional)
  Type: string
  
  Delete dry run only. Send it back to confirm a `match` delete.

- `message` (optional)
  Type: string
  
  Delete only. What happened or will happen

- 202: Delete of more than 100 contacts queued to run in the background

Content type: application/json

Type: object

- `action` (required)
  Type: string
  
  enum: ["delete"]

- `status` (required)
  Type: string
  
  enum: ["queued"]

- `contact_count` (required)
  Type: integer

- `message` (required)
  Type: string

- 422: 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).

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/contacts/bulk' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "action_type": "add_to_list",
  "ids": [
    0
  ],
  "list_id": 0,
  "match": {
    "search": "string",
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ],
    "list_id": 0,
    "tag": "string",
    "source": "string"
  },
  "dry_run": true,
  "selection_digest": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "action_type": "add_to_list",
  "ids": [
    0
  ],
  "list_id": 0,
  "match": {
    "search": "string",
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ],
    "list_id": 0,
    "tag": "string",
    "source": "string"
  },
  "dry_run": true,
  "selection_digest": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/contacts/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "action_type": "add_to_list",
  "ids": [
    0
  ],
  "list_id": 0,
  "match": {
    "search": "string",
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ],
    "list_id": 0,
    "tag": "string",
    "source": "string"
  },
  "dry_run": true,
  "selection_digest": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/contacts/bulk',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a contact

`GET /v1/my/contacts/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Contact with channels

Content type: application/json

Type: object

Schema: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `uuid` (optional)
  Type: string, uuid

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `source` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `flag_emoji` (optional)
  Type: string; nullable
  
  Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `subscribed_phone` (optional)
  Type: boolean

- `subscribed_email` (optional)
  Type: boolean

- `email` (optional)
  Type: string, email; nullable
  
  Convenience value for the preferred email channel. Full channel detail remains in channels[].

- `subscribed` (optional)
  Type: object
  
  Denormalized subscription summary by channel family.
  
  - `email` (optional)
    Type: boolean
  
  - `phone` (optional)
    Type: boolean

- `verification_status` (optional)
  Type: string
  
  enum: ["verified","suppressed","unverified"]

- `verification_result` (optional)
  Type: string; nullable
  
  Newest list-verification result for the contact's email; null when never checked.
  
  enum: ["valid","invalid","disposable","catchall","unknown",null]

- `enrichment_status` (optional)
  Type: string
  
  enum: ["enriched","not_enriched"]

- `mailbox_provider` (optional)
  Type: string
  
  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.
  
  
  enum: ["gmail","apple","outlook","corporate","unknown"]

- `list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `last_interacted_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `engagement` (optional)
  Type: object; nullable
  
  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.
  
  
  - `rating` (optional)
    Type: string
    
    Five-tier engagement rating based on recency of opens and clicks.
    
    enum: ["engaged","warm","cooling","dormant","never"]
  
  - `emails_sent` (optional)
    Type: integer
  
  - `unique_opens` (optional)
    Type: integer
  
  - `clicks` (optional)
    Type: integer
  
  - `open_rate` (optional)
    Type: number, float; nullable
  
  - `click_rate` (optional)
    Type: number, float; nullable
  
  - `last_opened_at` (optional)
    Type: string, date-time; nullable
  
  - `last_clicked_at` (optional)
    Type: string, date-time; nullable

- `channels` (optional)
  Type: array
  
  Items:
    Reference: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/contacts/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/contacts/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a contact

`DELETE /v1/my/contacts/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted contact

Content type: application/json

Type: object

Schema: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `uuid` (optional)
  Type: string, uuid

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `source` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `flag_emoji` (optional)
  Type: string; nullable
  
  Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `subscribed_phone` (optional)
  Type: boolean

- `subscribed_email` (optional)
  Type: boolean

- `email` (optional)
  Type: string, email; nullable
  
  Convenience value for the preferred email channel. Full channel detail remains in channels[].

- `subscribed` (optional)
  Type: object
  
  Denormalized subscription summary by channel family.
  
  - `email` (optional)
    Type: boolean
  
  - `phone` (optional)
    Type: boolean

- `verification_status` (optional)
  Type: string
  
  enum: ["verified","suppressed","unverified"]

- `verification_result` (optional)
  Type: string; nullable
  
  Newest list-verification result for the contact's email; null when never checked.
  
  enum: ["valid","invalid","disposable","catchall","unknown",null]

- `enrichment_status` (optional)
  Type: string
  
  enum: ["enriched","not_enriched"]

- `mailbox_provider` (optional)
  Type: string
  
  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.
  
  
  enum: ["gmail","apple","outlook","corporate","unknown"]

- `list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `last_interacted_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `engagement` (optional)
  Type: object; nullable
  
  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.
  
  
  - `rating` (optional)
    Type: string
    
    Five-tier engagement rating based on recency of opens and clicks.
    
    enum: ["engaged","warm","cooling","dormant","never"]
  
  - `emails_sent` (optional)
    Type: integer
  
  - `unique_opens` (optional)
    Type: integer
  
  - `clicks` (optional)
    Type: integer
  
  - `open_rate` (optional)
    Type: number, float; nullable
  
  - `click_rate` (optional)
    Type: number, float; nullable
  
  - `last_opened_at` (optional)
    Type: string, date-time; nullable
  
  - `last_clicked_at` (optional)
    Type: string, date-time; nullable

- `channels` (optional)
  Type: array
  
  Items:
    Reference: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md); Type: object

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/contacts/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/contacts/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a contact

`PATCH /v1/my/contacts/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `first_name` (optional)
  Type: string

- `last_name` (optional)
  Type: string

- `email` (optional)
  Type: string, 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).

- `phone` (optional)
  Type: string
  
  E.164 format. Several contacts in a brand may share a phone, so a phone another contact holds is accepted.

- `source` (optional)
  Type: string

- `country_code` (optional)
  Type: string

- `opt_in` (optional)
  Type: boolean; nullable
  
  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_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `channels_attributes` (optional)
  Type: array
  
  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.
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `kind` (optional)
      Type: string
      
      enum: ["email","phone"]
    
    - `value` (optional)
      Type: string
    
    - `subscribed` (optional)
      Type: boolean
      
      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.
    
    - `_destroy` (optional)
      Type: boolean

Responses:

- 200: Updated contact

Content type: application/json

Type: object

Schema: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `uuid` (optional)
  Type: string, uuid

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `source` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `flag_emoji` (optional)
  Type: string; nullable
  
  Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `subscribed_phone` (optional)
  Type: boolean

- `subscribed_email` (optional)
  Type: boolean

- `email` (optional)
  Type: string, email; nullable
  
  Convenience value for the preferred email channel. Full channel detail remains in channels[].

- `subscribed` (optional)
  Type: object
  
  Denormalized subscription summary by channel family.
  
  - `email` (optional)
    Type: boolean
  
  - `phone` (optional)
    Type: boolean

- `verification_status` (optional)
  Type: string
  
  enum: ["verified","suppressed","unverified"]

- `verification_result` (optional)
  Type: string; nullable
  
  Newest list-verification result for the contact's email; null when never checked.
  
  enum: ["valid","invalid","disposable","catchall","unknown",null]

- `enrichment_status` (optional)
  Type: string
  
  enum: ["enriched","not_enriched"]

- `mailbox_provider` (optional)
  Type: string
  
  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.
  
  
  enum: ["gmail","apple","outlook","corporate","unknown"]

- `list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `last_interacted_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `engagement` (optional)
  Type: object; nullable
  
  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.
  
  
  - `rating` (optional)
    Type: string
    
    Five-tier engagement rating based on recency of opens and clicks.
    
    enum: ["engaged","warm","cooling","dormant","never"]
  
  - `emails_sent` (optional)
    Type: integer
  
  - `unique_opens` (optional)
    Type: integer
  
  - `clicks` (optional)
    Type: integer
  
  - `open_rate` (optional)
    Type: number, float; nullable
  
  - `click_rate` (optional)
    Type: number, float; nullable
  
  - `last_opened_at` (optional)
    Type: string, date-time; nullable
  
  - `last_clicked_at` (optional)
    Type: string, date-time; nullable

- `channels` (optional)
  Type: array
  
  Items:
    Reference: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md); Type: object

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/contacts/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "opt_in": true,
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "_destroy": true
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "opt_in": true,
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "_destroy": true
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/contacts/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "opt_in": true,
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "_destroy": true
    }
  ]
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/contacts/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Quote profile enrichment for Contacts or supplied Leads

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Exactly one same-Brand selection. Existing identity and profile ownership are preserved.

Schema: [ProfileEnrichmentAudience](https://docs.nitrosend.com/api/schemas/profileenrichmentaudience-4408908270.md)

- `contact_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100
  
  uniqueItems: true
  
  Items:
    Type: integer

oneOf:
  Type: unknown
  
  Must not match:
    Type: unknown

Responses:

- 200: Exact maximum-charge quote and work classification

Content type: application/json

Type: object

Schema: [ContactEnrichmentQuote](https://docs.nitrosend.com/api/schemas/contactenrichmentquote-8152a7af54.md)

- `quote_digest` (optional)
  Type: string
  
  pattern: "^[a-f0-9]{64}$"

- `selected_count` (required)
  Type: integer

- `already_current_count` (required)
  Type: integer

- `reusable_count` (required)
  Type: integer

- `provider_required_count` (required)
  Type: integer

- `unavailable_count` (required)
  Type: integer

- `maximum_billable_outcomes` (required)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contact_profile_enrichment"]

- `unit_rate_cents` (required)
  Type: string

- `maximum_charge_cents` (required)
  Type: integer

- `currency` (required)
  Type: string
  
  enum: ["USD"]

- `price_book_version` (required)
  Type: string

- `available` (required)
  Type: boolean

- `reason` (optional)
  Type: string; nullable

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/contacts/enrichment/quote' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/enrichment/quote', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/contacts/enrichment/quote',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Queue profile enrichment for Contacts or supplied Leads

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 128

Request body: application/json (required)

Type: object

Exactly one same-Brand selection. Existing identity and profile ownership are preserved.

Schema: [ProfileEnrichmentAudience](https://docs.nitrosend.com/api/schemas/profileenrichmentaudience-4408908270.md)

- `contact_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100
  
  uniqueItems: true
  
  Items:
    Type: integer

oneOf:
  Type: unknown
  
  Must not match:
    Type: unknown

Responses:

- 200: Exact idempotent replay

Content type: application/json

Type: object

Schema: [ContactEnrichmentDispatch](https://docs.nitrosend.com/api/schemas/contactenrichmentdispatch-1ed624bab5.md)

- `selected_count` (required)
  Type: integer

- `queued_count` (required)
  Type: integer

- `already_current_count` (required)
  Type: integer

- `reusable_count` (required)
  Type: integer

- `provider_required_count` (required)
  Type: integer

- `unavailable_count` (required)
  Type: integer

- `maximum_charge_cents` (required)
  Type: integer

- `currency` (required)
  Type: string
  
  enum: ["USD"]

- `price_book_version` (required)
  Type: string

- `idempotent_replay` (required)
  Type: boolean

- 202: Enrichment queued

Content type: application/json

Type: object

Schema: [ContactEnrichmentDispatch](https://docs.nitrosend.com/api/schemas/contactenrichmentdispatch-1ed624bab5.md)

- `selected_count` (required)
  Type: integer

- `queued_count` (required)
  Type: integer

- `already_current_count` (required)
  Type: integer

- `reusable_count` (required)
  Type: integer

- `provider_required_count` (required)
  Type: integer

- `unavailable_count` (required)
  Type: integer

- `maximum_charge_cents` (required)
  Type: integer

- `currency` (required)
  Type: string
  
  enum: ["USD"]

- `price_book_version` (required)
  Type: string

- `idempotent_replay` (required)
  Type: boolean

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 402: Account funding changed before the enrichment hold was created

Content type: application/json

Type: object

Schema: [ContactEnrichmentFundingRequired](https://docs.nitrosend.com/api/schemas/contactenrichmentfundingrequired-a1729c37a3.md)

- `code` (required)
  Type: string
  
  const: "insufficient_balance"

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (required)
  Type: string
  
  const: "insufficient_balance"

- `currency` (required)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `required_cents` (required)
  Type: integer
  
  minimum: 0

- `available_cents` (required)
  Type: integer

- `reserved_cents` (required)
  Type: integer
  
  minimum: 0

- `shortfall_cents` (required)
  Type: integer
  
  minimum: 0

- `funding` (required)
  Type: object
  
  Additional properties: true

- `recovery_action` (required)
  Type: object
  
  Additional properties: true

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- 409: Idempotency-Key reused with different Contact IDs

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/contacts/enrichment' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/enrichment', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/contacts/enrichment',
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Unified activity timeline for a contact

`GET /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `cursor` (query, string, optional) - Opaque keyset cursor from a prior `next_cursor`.
  Type: string

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: A page of timeline entries, newest first

Content type: application/json

Type: object

- `entries` (optional)
  Type: array
  
  Items:
    Reference: [TimelineEntry](https://docs.nitrosend.com/api/schemas/timelineentry-94a0220211.md); Type: object
    
    One normalised, whitelisted entry in a contact's unified timeline.

- `next_cursor` (optional)
  Type: string; nullable

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/contacts/0/timeline?limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/0/timeline?limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/contacts/0/timeline?limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Enrichment facts for a contact

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: The contact's resolved enrichment rows

Content type: application/json

Type: object

- `rows` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `key` (optional)
      Type: string
    
    - `value` (optional)
      Type: unknown
    
    - `group` (optional)
      Type: string
      
      enum: ["professional","company","location","contact_intelligence","other"]
    
    - `display_value` (optional)
      Type: string
      
      Human-readable value using the field catalog's shared presentation contract.
    
    - `value_type` (optional)
      Type: string
    
    - `confidence` (optional)
      Type: number; nullable
    
    - `stale` (optional)
      Type: boolean
    
    - `synced_at` (optional)
      Type: string, date-time; nullable
    
    - `integration_label` (optional)
      Type: string; nullable
      
      Present only for facts from a connected integration.

- `field_count` (optional)
  Type: integer

- `summary` (optional)
  Type: object
  
  - `field_count` (optional)
    Type: integer
  
  - `stale_count` (optional)
    Type: integer
  
  - `latest_synced_at` (optional)
    Type: string, date-time; nullable
  
  - `groups` (optional)
    Type: object
    
    Additional properties: 
      Type: integer

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/contacts/0/enrichment' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/0/enrichment', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/contacts/0/enrichment',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List the field catalog for this account

`GET /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Field catalog rows ordered by category and label

Content type: application/json

Type: array

Items:
  Reference: [FieldCatalog](https://docs.nitrosend.com/api/schemas/fieldcatalog-51b67420ab.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/contacts/fields' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/fields', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/contacts/fields',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a field catalog row (owner/admin only)

`PATCH /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `promoted` (optional)
  Type: boolean
  
  Pin this field as a default column in the contacts grid.

- `label` (optional)
  Type: string
  
  Override the human-readable label for this field.

Responses:

- 200: Updated field catalog row

Content type: application/json

Type: object

Schema: [FieldCatalog](https://docs.nitrosend.com/api/schemas/fieldcatalog-51b67420ab.md)

- `id` (required)
  Type: integer

- `key` (required)
  Type: string
  
  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`).
  

- `category` (required)
  Type: string
  
  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)
  
  
  enum: ["contact","custom","enrichment","engagement","tag"]

- `field_type` (required)
  Type: string
  
  Inferred from the first observed value; pinned and never flipped.
  
  enum: ["string","number","boolean","date","enum"]

- `presentation_type` (required)
  Type: string
  
  Shared presentation contract used by fact displays and generated merge tags.
  
  enum: ["text","number","currency","percent","date","datetime","boolean","enum"]

- `presentation_options` (required)
  Type: object
  
  Provider-supplied formatting metadata such as decimal precision,
  currency-code field path, unit scale, or percentage multiplier.
  
  
  Additional properties: true

- `label` (required)
  Type: string
  
  Human-readable label. Defaults to a humanised version of the key.

- `display_label` (optional)
  Type: string
  
  Source-qualified field label suitable for display.

- `source_key` (optional)
  Type: string; nullable

- `source_name` (optional)
  Type: string; nullable

- `object_label` (optional)
  Type: string; nullable

- `source_field_label` (optional)
  Type: string; nullable

- `merge_tag` (optional)
  Type: string; nullable
  
  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.
  

- `promoted` (required)
  Type: boolean
  
  Whether this field is pinned as a default column in the contacts grid.

- `fill_rate` (optional)
  Type: string; nullable
  
  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:
  
  ```json
  "75.0"
  ```

- `fill_rate_refreshed_at` (optional)
  Type: string, date-time; nullable
  
  When fill_rate was last computed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/contacts/fields/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "promoted": true,
  "label": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "promoted": true,
  "label": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/contacts/fields/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "promoted": true,
  "label": "string"
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/contacts/fields/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Ingest an image media asset

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `image_data` (optional)
  Type: string
  
  Raw base64 image bytes or a data URL. PNG, JPEG, GIF, or WebP only; decoded size must be under 10MB.

- `image_url` (optional)
  Type: string, uri
  
  Public PNG, JPEG, GIF, or WebP URL to ingest when Nitro-hosted permanence is desired.

- `signed_id` (optional)
  Type: string
  
  Active Storage blob signed ID returned by `/v1/direct_uploads` after uploading bytes with purpose `image` or `media_asset`.

- `filename` (optional)
  Type: string
  
  Original filename for image_data uploads, or optional filename override for image_url/signed_id sources.

- `content_type` (optional)
  Type: string; nullable
  
  Optional MIME type hint when image_data is raw base64 rather than a data URL.

Request body: multipart/form-data (required)

Type: object

- `file` (optional)
  Type: string, binary
  
  PNG, JPEG, GIF, or WebP file upload. Must be under 10MB.

- `filename` (optional)
  Type: string
  
  Optional filename override.

- `content_type` (optional)
  Type: string; nullable
  
  Optional MIME type override.

Responses:

- 201: Ingested image asset

Content type: application/json

Type: object

Schema: [ImageAsset](https://docs.nitrosend.com/api/schemas/imageasset-04f1a1a7d1.md)

- `media_kind` (optional)
  Type: string
  
  enum: ["image"]

- `media_url` (optional)
  Type: string, uri

- `image_url` (optional)
  Type: string, uri

- `signed_id` (optional)
  Type: string

- `filename` (optional)
  Type: string

- `content_type` (optional)
  Type: string

- `byte_size` (optional)
  Type: integer

- `width` (optional)
  Type: integer; nullable
  
  Intrinsic pixel width when detectable.

- `height` (optional)
  Type: integer; nullable
  
  Intrinsic pixel height when detectable.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/images' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "image_data": "string",
  "image_url": "https://example.com",
  "signed_id": "string",
  "filename": "string",
  "content_type": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "image_data": "string",
  "image_url": "https://example.com",
  "signed_id": "string",
  "filename": "string",
  "content_type": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/images', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "image_data": "string",
  "image_url": "https://example.com",
  "signed_id": "string",
  "filename": "string",
  "content_type": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/images',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Reserve a direct-upload blob

`POST /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [DirectUploadCreateRequest](https://docs.nitrosend.com/api/schemas/directuploadcreaterequest-7b79eba02f.md)

- `purpose` (optional)
  Type: string
  
  Set to `import` for CSV contact imports, or `image`/`media_asset` for image media assets.
  
  enum: ["import","image","media_asset"]

- `blob` (required)
  Type: object
  
  - `filename` (required)
    Type: string
    
    Example:
    
    ```json
    "contacts.csv"
    ```
  
  - `byte_size` (required)
    Type: integer
    
    Example:
    
    ```json
    1048576
    ```
  
  - `checksum` (required)
    Type: string
    
    Base64-encoded MD5 checksum for Active Storage direct upload.
  
  - `content_type` (optional)
    Type: string
    
    Example:
    
    ```json
    "text/csv"
    ```
  
  - `metadata` (optional)
    Type: object
    
    Additional properties: true

Responses:

- 200: Direct-upload reservation

Content type: application/json

Type: object

Schema: [DirectUpload](https://docs.nitrosend.com/api/schemas/directupload-ca32662919.md)

- `signed_id` (optional)
  Type: string
  
  Submit this value to endpoints that consume direct uploads.

- `filename` (optional)
  Type: string

- `byte_size` (optional)
  Type: integer

- `content_type` (optional)
  Type: string; nullable

- `direct_upload` (optional)
  Type: object
  
  - `url` (optional)
    Type: string, uri
  
  - `headers` (optional)
    Type: object
    
    Additional properties: 
      Type: string

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/direct_uploads' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "purpose": "import",
  "blob": {
    "filename": "contacts.csv",
    "byte_size": 1048576,
    "checksum": "string",
    "content_type": "text/csv",
    "metadata": {}
  }
}'
```

### JavaScript

```javascript
const body = `{
  "purpose": "import",
  "blob": {
    "filename": "contacts.csv",
    "byte_size": 1048576,
    "checksum": "string",
    "content_type": "text/csv",
    "metadata": {}
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/direct_uploads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "purpose": "import",
  "blob": {
    "filename": "contacts.csv",
    "byte_size": 1048576,
    "checksum": "string",
    "content_type": "text/csv",
    "metadata": {}
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/direct_uploads',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List import jobs

`GET /v1/my/imports`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated import jobs

Content type: application/json

Type: array

Items:
  Reference: [Import](https://docs.nitrosend.com/api/schemas/import-2cff9baabf.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/imports?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/imports?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/imports?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Start a CSV import

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `signed_id` (required)
  Type: string
  
  Active Storage blob signed ID returned by `/v1/direct_uploads`.

- `resource` (optional)
  Type: string
  
  default: "contacts"
  
  enum: ["contacts","leads"]

- `parser` (optional)
  Type: string
  
  default: "default"
  
  enum: ["default"]

- `dry_run` (optional)
  Type: boolean
  
  default: false

- `columns` (optional)
  Type: unknown
  
  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.
  
  
  Example:
  
  ```json
  {
    "email": "Email",
    "first_name": "First Name",
    "email_status": "Subscribed",
    "email_opt_out": "Unsubscribed",
    "opt_in_at": "Opt In Date"
  }
  ```
  
  oneOf:
    Type: object
    
    Additional properties: 
      Type: string; nullable
  
    Type: string
  
    Type: null

- `options` (optional)
  Type: unknown
  
  Import options as a JSON object or JSON string.
  
  Example:
  
  ```json
  {
    "list_ids": [
      88
    ]
  }
  ```
  
  oneOf:
    Type: object
    
    - `email_action` (optional)
      Type: string
      
      Optional whole-file action for email in this brand. Omit to preserve subscription choices; recognizable file unsubscribes are always honored.
      
      enum: ["unsubscribe","block"]
    
    - `list_ids` (optional)
      Type: array
      
      Items:
        Type: integer
    
    - `start_flows` (optional)
      Type: boolean
      
      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.
      
      default: false
  
    Type: string

Responses:

- 201: Import queued

Content type: application/json

Type: object

Schema: [Import](https://docs.nitrosend.com/api/schemas/import-2cff9baabf.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `parser` (optional)
  Type: string
  
  enum: ["default"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","failed","canceled","complete","contact_us"]

- `total_rows` (optional)
  Type: integer; nullable

- `success_rows` (optional)
  Type: integer; nullable

- `failed_rows` (optional)
  Type: integer; nullable

- `email_rows` (optional)
  Type: object; nullable
  
  Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.
  
  - `subscribed` (optional)
    Type: integer
  
  - `unsubscribed` (optional)
    Type: integer
  
  - `blocked` (optional)
    Type: integer

- `warning_rows` (optional)
  Type: integer
  
  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.

- `progress` (optional)
  Type: object
  
  Canonical live-progress block (the single progress representation). `pct` is the only percent source; a null `pct` means indeterminate.
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `import_errors` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `import_warnings` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `columns` (optional)
  Type: object; nullable
  
  Additional properties: true

- `options` (optional)
  Type: object; nullable
  
  Additional properties: true

- `assigned_list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `assigned_lists` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string

- `guardrail` (optional)
  Reference: [ImportGuardrail](https://docs.nitrosend.com/api/schemas/importguardrail-bcbfe33303.md); Type: object
  
  How this import stands against the account's standing row limit.

- `flows_not_started` (optional)
  Type: object; nullable
  
  Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.
  
  - `flows` (required)
    Type: array
    
    Items:
      Type: object
      
      - `id` (optional)
        Type: integer
      
      - `name` (optional)
        Type: string
  
  - `message` (required)
    Type: string
  
  - `next_step` (required)
    Type: string

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/imports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "signed_id": "string",
  "resource": "contacts",
  "parser": "default",
  "dry_run": false,
  "columns": {
    "email": "Email",
    "first_name": "First Name",
    "email_status": "Subscribed",
    "email_opt_out": "Unsubscribed",
    "opt_in_at": "Opt In Date"
  },
  "options": {
    "list_ids": [
      88
    ]
  }
}'
```

### JavaScript

```javascript
const body = `{
  "signed_id": "string",
  "resource": "contacts",
  "parser": "default",
  "dry_run": false,
  "columns": {
    "email": "Email",
    "first_name": "First Name",
    "email_status": "Subscribed",
    "email_opt_out": "Unsubscribed",
    "opt_in_at": "Opt In Date"
  },
  "options": {
    "list_ids": [
      88
    ]
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/imports', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "signed_id": "string",
  "resource": "contacts",
  "parser": "default",
  "dry_run": false,
  "columns": {
    "email": "Email",
    "first_name": "First Name",
    "email_status": "Subscribed",
    "email_opt_out": "Unsubscribed",
    "opt_in_at": "Opt In Date"
  },
  "options": {
    "list_ids": [
      88
    ]
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/imports',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get import schema metadata

`GET /v1/my/imports/spec`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `resource` (query, string, optional) - Optional resource name. Omit to list all schemas.
  Type: string
  
  enum: ["contacts","leads"]

Responses:

- 200: Import schema metadata

Content type: application/json

Type: unknown

oneOf:
  Reference: [ImportSpec](https://docs.nitrosend.com/api/schemas/importspec-1405feb4a6.md); Type: object

  Type: object
  
  Additional properties: 
    Reference: [ImportSpec](https://docs.nitrosend.com/api/schemas/importspec-1405feb4a6.md); Type: object

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/imports/spec' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/imports/spec', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/imports/spec',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get import job status

`GET /v1/my/imports/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Import job with status, counts, and row errors

Content type: application/json

Type: object

Schema: [Import](https://docs.nitrosend.com/api/schemas/import-2cff9baabf.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `parser` (optional)
  Type: string
  
  enum: ["default"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","failed","canceled","complete","contact_us"]

- `total_rows` (optional)
  Type: integer; nullable

- `success_rows` (optional)
  Type: integer; nullable

- `failed_rows` (optional)
  Type: integer; nullable

- `email_rows` (optional)
  Type: object; nullable
  
  Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.
  
  - `subscribed` (optional)
    Type: integer
  
  - `unsubscribed` (optional)
    Type: integer
  
  - `blocked` (optional)
    Type: integer

- `warning_rows` (optional)
  Type: integer
  
  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.

- `progress` (optional)
  Type: object
  
  Canonical live-progress block (the single progress representation). `pct` is the only percent source; a null `pct` means indeterminate.
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `import_errors` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `import_warnings` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `columns` (optional)
  Type: object; nullable
  
  Additional properties: true

- `options` (optional)
  Type: object; nullable
  
  Additional properties: true

- `assigned_list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `assigned_lists` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string

- `guardrail` (optional)
  Reference: [ImportGuardrail](https://docs.nitrosend.com/api/schemas/importguardrail-bcbfe33303.md); Type: object
  
  How this import stands against the account's standing row limit.

- `flows_not_started` (optional)
  Type: object; nullable
  
  Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.
  
  - `flows` (required)
    Type: array
    
    Items:
      Type: object
      
      - `id` (optional)
        Type: integer
      
      - `name` (optional)
        Type: string
  
  - `message` (required)
    Type: string
  
  - `next_step` (required)
    Type: string

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/imports/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/imports/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/imports/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete an import record

`DELETE /v1/my/imports/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted import

Content type: application/json

Type: object

Schema: [Import](https://docs.nitrosend.com/api/schemas/import-2cff9baabf.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `parser` (optional)
  Type: string
  
  enum: ["default"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","failed","canceled","complete","contact_us"]

- `total_rows` (optional)
  Type: integer; nullable

- `success_rows` (optional)
  Type: integer; nullable

- `failed_rows` (optional)
  Type: integer; nullable

- `email_rows` (optional)
  Type: object; nullable
  
  Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.
  
  - `subscribed` (optional)
    Type: integer
  
  - `unsubscribed` (optional)
    Type: integer
  
  - `blocked` (optional)
    Type: integer

- `warning_rows` (optional)
  Type: integer
  
  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.

- `progress` (optional)
  Type: object
  
  Canonical live-progress block (the single progress representation). `pct` is the only percent source; a null `pct` means indeterminate.
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `import_errors` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `import_warnings` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `columns` (optional)
  Type: object; nullable
  
  Additional properties: true

- `options` (optional)
  Type: object; nullable
  
  Additional properties: true

- `assigned_list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `assigned_lists` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string

- `guardrail` (optional)
  Reference: [ImportGuardrail](https://docs.nitrosend.com/api/schemas/importguardrail-bcbfe33303.md); Type: object
  
  How this import stands against the account's standing row limit.

- `flows_not_started` (optional)
  Type: object; nullable
  
  Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.
  
  - `flows` (required)
    Type: array
    
    Items:
      Type: object
      
      - `id` (optional)
        Type: integer
      
      - `name` (optional)
        Type: string
  
  - `message` (required)
    Type: string
  
  - `next_step` (required)
    Type: string

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/imports/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/imports/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/imports/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Cancel a pending or processing import

`POST /v1/my/imports/{id}/cancel`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Canceled import

Content type: application/json

Type: object

Schema: [Import](https://docs.nitrosend.com/api/schemas/import-2cff9baabf.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `parser` (optional)
  Type: string
  
  enum: ["default"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","failed","canceled","complete","contact_us"]

- `total_rows` (optional)
  Type: integer; nullable

- `success_rows` (optional)
  Type: integer; nullable

- `failed_rows` (optional)
  Type: integer; nullable

- `email_rows` (optional)
  Type: object; nullable
  
  Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.
  
  - `subscribed` (optional)
    Type: integer
  
  - `unsubscribed` (optional)
    Type: integer
  
  - `blocked` (optional)
    Type: integer

- `warning_rows` (optional)
  Type: integer
  
  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.

- `progress` (optional)
  Type: object
  
  Canonical live-progress block (the single progress representation). `pct` is the only percent source; a null `pct` means indeterminate.
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `import_errors` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `import_warnings` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `columns` (optional)
  Type: object; nullable
  
  Additional properties: true

- `options` (optional)
  Type: object; nullable
  
  Additional properties: true

- `assigned_list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `assigned_lists` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string

- `guardrail` (optional)
  Reference: [ImportGuardrail](https://docs.nitrosend.com/api/schemas/importguardrail-bcbfe33303.md); Type: object
  
  How this import stands against the account's standing row limit.

- `flows_not_started` (optional)
  Type: object; nullable
  
  Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.
  
  - `flows` (required)
    Type: array
    
    Items:
      Type: object
      
      - `id` (optional)
        Type: integer
      
      - `name` (optional)
        Type: string
  
  - `message` (required)
    Type: string
  
  - `next_step` (required)
    Type: string

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/imports/0/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/imports/0/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/imports/0/cancel',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List export jobs

`GET /v1/my/exports`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated export jobs

Content type: application/json

Type: array

Items:
  Reference: [Export](https://docs.nitrosend.com/api/schemas/export-3664895579.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/exports?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/exports?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/exports?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Start a contact export

`POST /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json

Type: object

- `resource` (optional)
  Type: string
  
  default: "contacts"
  
  enum: ["contacts","leads"]

- `search` (optional)
  Type: string
  
  Free-text filter, matching the contacts list search.

- `list_id` (optional)
  Type: integer
  
  Restrict the export to contacts in this list.

- `tag` (optional)
  Type: string
  
  Restrict the export to contacts with this tag.

Responses:

- 201: Export queued

Content type: application/json

Type: object

Schema: [Export](https://docs.nitrosend.com/api/schemas/export-3664895579.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `format` (optional)
  Type: string
  
  enum: ["csv"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","complete","failed"]

- `total_rows` (optional)
  Type: integer; nullable

- `rows_written` (optional)
  Type: integer
  
  Rows written so far; the live numerator against total_rows.

- `error_message` (optional)
  Type: string; nullable

- `ready` (optional)
  Type: boolean
  
  True once the export is complete and the file is available.

- `download_path` (optional)
  Type: string; nullable
  
  Path to download the CSV; present only when `ready` is true.

- `progress` (optional)
  Type: object
  
  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.
  
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
    
    Completion percentage, or null when indeterminate.
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer; nullable
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/exports' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "resource": "contacts",
  "search": "string",
  "list_id": 0,
  "tag": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "resource": "contacts",
  "search": "string",
  "list_id": 0,
  "tag": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/exports', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "resource": "contacts",
  "search": "string",
  "list_id": 0,
  "tag": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/exports',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get an export job

`GET /v1/my/exports/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Export job

Content type: application/json

Type: object

Schema: [Export](https://docs.nitrosend.com/api/schemas/export-3664895579.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `format` (optional)
  Type: string
  
  enum: ["csv"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","complete","failed"]

- `total_rows` (optional)
  Type: integer; nullable

- `rows_written` (optional)
  Type: integer
  
  Rows written so far; the live numerator against total_rows.

- `error_message` (optional)
  Type: string; nullable

- `ready` (optional)
  Type: boolean
  
  True once the export is complete and the file is available.

- `download_path` (optional)
  Type: string; nullable
  
  Path to download the CSV; present only when `ready` is true.

- `progress` (optional)
  Type: object
  
  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.
  
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
    
    Completion percentage, or null when indeterminate.
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer; nullable
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/exports/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/exports/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/exports/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Download a completed export file

`GET /v1/my/exports/{id}/download`

Returns the CSV file once the export status is `complete`.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: CSV file

Content type: text/csv

Type: string, binary

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Export is not ready

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/exports/0/download' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/exports/0/download', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/exports/0/download',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List contact lists (paginated)

`GET /v1/my/lists`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `name` (query, string, optional) - Exact case-insensitive list name filter
  Type: string

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated contact lists

Content type: application/json

Type: array

Items:
  Reference: [ContactList](https://docs.nitrosend.com/api/schemas/contactlist-1538131b0d.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/lists?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/lists?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/lists?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a contact list

`POST /v1/my/lists`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `name` (required)
  Type: string

- `segment_id` (optional)
  Type: integer; nullable

- `contact_ids` (optional)
  Type: array
  
  Items:
    Type: integer

Responses:

- 201: List created

Content type: application/json

Type: object

Schema: [ContactList](https://docs.nitrosend.com/api/schemas/contactlist-1538131b0d.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `contacts_count` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer; nullable

- `stale` (optional)
  Type: boolean

- `last_populated_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/lists' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/lists', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/lists',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a contact list

`GET /v1/my/lists/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Contact list

Content type: application/json

Type: object

Schema: [ContactList](https://docs.nitrosend.com/api/schemas/contactlist-1538131b0d.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `contacts_count` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer; nullable

- `stale` (optional)
  Type: boolean

- `last_populated_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/lists/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/lists/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/lists/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a contact list

`DELETE /v1/my/lists/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted list

Content type: application/json

Type: object

Schema: [ContactList](https://docs.nitrosend.com/api/schemas/contactlist-1538131b0d.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `contacts_count` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer; nullable

- `stale` (optional)
  Type: boolean

- `last_populated_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/lists/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/lists/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/lists/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a contact list

`PATCH /v1/my/lists/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `segment_id` (optional)
  Type: integer; nullable

- `contact_ids` (optional)
  Type: array
  
  Items:
    Type: integer

Responses:

- 200: Updated list

Content type: application/json

Type: object

Schema: [ContactList](https://docs.nitrosend.com/api/schemas/contactlist-1538131b0d.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `contacts_count` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer; nullable

- `stale` (optional)
  Type: boolean

- `last_populated_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/lists/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/lists/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/lists/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get delete warning metadata for a contact list

`GET /v1/my/lists/{id}/delete_warning`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Flows connected to this list

Content type: application/json

Type: object

Schema: [ListDeleteWarning](https://docs.nitrosend.com/api/schemas/listdeletewarning-595c1c5082.md)

- `campaign_names` (optional)
  Type: array
  
  Items:
    Type: string

- `flow_names` (optional)
  Type: array
  
  Items:
    Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/lists/0/delete_warning' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/lists/0/delete_warning', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/lists/0/delete_warning',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Add or remove existing contacts from a list by email

`POST /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

Schema: [BulkListContactsRequest](https://docs.nitrosend.com/api/schemas/bulklistcontactsrequest-04cb14683d.md)

- `action` (required)
  Type: string
  
  Add existing contacts to the list or remove them from it.
  
  enum: ["add","remove"]

- `emails` (required)
  Type: array
  
  minItems: 1
  
  maxItems: 500
  
  Items:
    Type: string, email

Responses:

- 200: Bulk list membership result

Content type: application/json

Type: object

Schema: [BulkListContactsResponse](https://docs.nitrosend.com/api/schemas/bulklistcontactsresponse-b3c5cc214e.md)

- `action` (optional)
  Type: string
  
  enum: ["add","remove"]

- `list_id` (optional)
  Type: integer

- `added` (optional)
  Type: integer
  
  Contacts newly added for add actions

- `removed` (optional)
  Type: integer
  
  Contacts removed for remove actions

- `already_in_list` (optional)
  Type: array
  
  Items:
    Type: string, email

- `not_in_list` (optional)
  Type: array
  
  Items:
    Type: string, email

- `not_found` (optional)
  Type: array
  
  Items:
    Type: string, email

- `invalid_emails` (optional)
  Type: array
  
  Items:
    Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/lists/0/contacts/bulk' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "action": "add",
  "emails": [
    "user@example.com"
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "action": "add",
  "emails": [
    "user@example.com"
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/lists/0/contacts/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "action": "add",
  "emails": [
    "user@example.com"
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/lists/0/contacts/bulk',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List all segments (paginated)

`GET /v1/my/segments`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 100
  
  maximum: 100

Responses:

- 200: Segments

Content type: application/json

Type: array

Items:
  Reference: [Segment](https://docs.nitrosend.com/api/schemas/segment-29ee089cce.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/segments?page=1&per=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/segments?page=1&per=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/segments?page=1&per=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a segment

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `name` (required)
  Type: string

- `filters` (required)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

Responses:

- 201: Segment created

Content type: application/json

Type: object

Schema: [Segment](https://docs.nitrosend.com/api/schemas/segment-29ee089cce.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `origin` (optional)
  Type: string
  
  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.
  
  
  enum: ["user","system"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `cached_count` (optional)
  Type: integer; nullable
  
  Last asynchronously refreshed contact count for this segment.

- `count_computed_at` (optional)
  Type: string, date-time; nullable
  
  When `cached_count` was last refreshed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/segments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/segments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/segments',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a segment

`GET /v1/my/segments/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Segment

Content type: application/json

Type: object

Schema: [Segment](https://docs.nitrosend.com/api/schemas/segment-29ee089cce.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `origin` (optional)
  Type: string
  
  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.
  
  
  enum: ["user","system"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `cached_count` (optional)
  Type: integer; nullable
  
  Last asynchronously refreshed contact count for this segment.

- `count_computed_at` (optional)
  Type: string, date-time; nullable
  
  When `cached_count` was last refreshed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/segments/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/segments/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/segments/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a segment

`DELETE /v1/my/segments/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted segment

Content type: application/json

Type: object

Schema: [Segment](https://docs.nitrosend.com/api/schemas/segment-29ee089cce.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `origin` (optional)
  Type: string
  
  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.
  
  
  enum: ["user","system"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `cached_count` (optional)
  Type: integer; nullable
  
  Last asynchronously refreshed contact count for this segment.

- `count_computed_at` (optional)
  Type: string, date-time; nullable
  
  When `cached_count` was last refreshed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/segments/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/segments/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/segments/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a segment

`PATCH /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

Responses:

- 200: Updated segment

Content type: application/json

Type: object

Schema: [Segment](https://docs.nitrosend.com/api/schemas/segment-29ee089cce.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `origin` (optional)
  Type: string
  
  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.
  
  
  enum: ["user","system"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `cached_count` (optional)
  Type: integer; nullable
  
  Last asynchronously refreshed contact count for this segment.

- `count_computed_at` (optional)
  Type: string, date-time; nullable
  
  When `cached_count` was last refreshed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/segments/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/segments/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/segments/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Count contacts matching filters

`POST /v1/my/segments/count`

Preview how many contacts match a set of segment filters
without creating or saving a segment.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

Responses:

- 200: Contact count

Content type: application/json

Type: object

- `count` (optional)
  Type: integer

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/segments/count' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/segments/count', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/segments/count',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Preview contacts matching filters

`POST /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

Responses:

- 200: Segment preview

Content type: application/json

Type: object

Schema: [SegmentPreview](https://docs.nitrosend.com/api/schemas/segmentpreview-69e4423dce.md)

- `count` (optional)
  Type: integer
  
  Live count of contacts matching the supplied filters.

- `sample` (optional)
  Type: array
  
  Bounded contact sample for quick verification.
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `email` (optional)
      Type: string; nullable
    
    - `name` (optional)
      Type: string; nullable

- `overlap` (optional)
  Type: array
  
  Bounded overlap with existing segments.
  
  Items:
    Type: object
    
    - `segment_id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string
    
    - `overlap_count` (optional)
      Type: integer

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/segments/preview' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/segments/preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/segments/preview',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List saved views visible to the current user

`GET /v1/my/saved_views`

Returns all shared views in the current account plus the caller's own
private views. Optionally filtered by surface.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `surface` (query, string, optional) - Filter views by surface
  Type: string
  
  enum: ["contacts","sending","activity"]

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Saved views

Content type: application/json

Type: array

Items:
  Reference: [SavedView](https://docs.nitrosend.com/api/schemas/savedview-cb60b3ba7b.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/saved_views?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/saved_views?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/saved_views?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a saved view

`POST /v1/my/saved_views`

Creates a new saved view owned by the current user. Defaults to private
visibility if not specified.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `surface` (required)
  Type: string
  
  enum: ["contacts","sending","activity"]

- `name` (required)
  Type: string
  
  maxLength: 100

- `visibility` (optional)
  Type: string
  
  default: "private"
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

Responses:

- 201: Saved view created

Content type: application/json

Type: object

Schema: [SavedView](https://docs.nitrosend.com/api/schemas/savedview-cb60b3ba7b.md)

- `id` (optional)
  Type: integer

- `surface` (optional)
  Type: string
  
  enum: ["contacts","sending","activity"]

- `name` (optional)
  Type: string

- `visibility` (optional)
  Type: string
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

- `owner` (optional)
  Type: boolean
  
  True when the current user is the creator of this view

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/saved_views' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "surface": "contacts",
  "name": "string",
  "visibility": "private",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "layout": {
    "columns": [
      "string"
    ],
    "sort": {
      "field": "string",
      "dir": "asc"
    }
  }
}'
```

### JavaScript

```javascript
const body = `{
  "surface": "contacts",
  "name": "string",
  "visibility": "private",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "layout": {
    "columns": [
      "string"
    ],
    "sort": {
      "field": "string",
      "dir": "asc"
    }
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/saved_views', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "surface": "contacts",
  "name": "string",
  "visibility": "private",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "layout": {
    "columns": [
      "string"
    ],
    "sort": {
      "field": "string",
      "dir": "asc"
    }
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/saved_views',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Delete a saved view

`DELETE /v1/my/saved_views/{id}`

Deletes a saved view. Allowed only for the creator or the account owner.
Other members receive 403.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted saved view

Content type: application/json

Type: object

Schema: [SavedView](https://docs.nitrosend.com/api/schemas/savedview-cb60b3ba7b.md)

- `id` (optional)
  Type: integer

- `surface` (optional)
  Type: string
  
  enum: ["contacts","sending","activity"]

- `name` (optional)
  Type: string

- `visibility` (optional)
  Type: string
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

- `owner` (optional)
  Type: boolean
  
  True when the current user is the creator of this view

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/saved_views/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/saved_views/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/saved_views/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a saved view

`PATCH /v1/my/saved_views/{id}`

Updates a saved view. Allowed only for the creator or the account owner.
Other members receive 403.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string
  
  maxLength: 100

- `visibility` (optional)
  Type: string
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

Responses:

- 200: Updated saved view

Content type: application/json

Type: object

Schema: [SavedView](https://docs.nitrosend.com/api/schemas/savedview-cb60b3ba7b.md)

- `id` (optional)
  Type: integer

- `surface` (optional)
  Type: string
  
  enum: ["contacts","sending","activity"]

- `name` (optional)
  Type: string

- `visibility` (optional)
  Type: string
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

- `owner` (optional)
  Type: boolean
  
  True when the current user is the creator of this view

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/saved_views/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "visibility": "private",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "layout": {
    "columns": [
      "string"
    ],
    "sort": {
      "field": "string",
      "dir": "asc"
    }
  }
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "visibility": "private",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "layout": {
    "columns": [
      "string"
    ],
    "sort": {
      "field": "string",
      "dir": "asc"
    }
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/saved_views/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "visibility": "private",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "layout": {
    "columns": [
      "string"
    ],
    "sort": {
      "field": "string",
      "dir": "asc"
    }
  }
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/saved_views/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Fork a saved view into a new private view

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 201: Forked saved view

Content type: application/json

Type: object

Schema: [SavedView](https://docs.nitrosend.com/api/schemas/savedview-cb60b3ba7b.md)

- `id` (optional)
  Type: integer

- `surface` (optional)
  Type: string
  
  enum: ["contacts","sending","activity"]

- `name` (optional)
  Type: string

- `visibility` (optional)
  Type: string
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

- `owner` (optional)
  Type: boolean
  
  True when the current user is the creator of this view

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/saved_views/0/fork' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/saved_views/0/fork', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/saved_views/0/fork',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Read the current brand's next actions and work in progress

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1
  
  minimum: 1
  
  maximum: 100

- `through` (query, boolean, optional) - Return the prefix through this page to refresh an expanded queue in one read.
  Type: boolean
  
  default: false

Responses:

- 200: Current actions and next-page pointer (not a total count)

Content type: application/json

Type: object

- `items` (required)
  Type: array
  
  Items:
    Reference: [WorkspaceAttentionItem](https://docs.nitrosend.com/api/schemas/workspaceattentionitem-01416e6e3e.md); Type: object

- `next_page` (required)
  Type: integer; nullable

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/workspace/attention?page=1&through=false' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/workspace/attention?page=1&through=false', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/workspace/attention?page=1&through=false',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Read agent and API control-plane activity for the current brand

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `source` (query, string, optional)
  Type: string
  
  enum: ["mcp","nitrollm","api"]

- `outcome` (query, string, optional)
  Type: string
  
  enum: ["ok","error","unknown"]

- `before` (query, integer, optional) - Read older entries using the previous response's next_cursor.
  Type: integer
  
  minimum: 1

Responses:

- 200: Recorded activity and continuation cursor

Content type: application/json

Type: object

- `items` (required)
  Type: array
  
  Items:
    Reference: [WorkspaceActivityItem](https://docs.nitrosend.com/api/schemas/workspaceactivityitem-fae1c02ca7.md); Type: object

- `next_cursor` (required)
  Type: integer; nullable

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/workspace/activity' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/workspace/activity', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/workspace/activity',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Search the current brand beyond locally loaded pages

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `q` (query, string, optional)
  Type: string
  
  maxLength: 100

Responses:

- 200: Bounded matches with application navigation targets

Content type: application/json

Type: object

- `items` (required)
  Type: array
  
  Items:
    Type: object
    
    - `id` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `group` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["campaign","flow","list","contact"]
    
    - `to` (required)
      Reference: [WorkspaceRoute](https://docs.nitrosend.com/api/schemas/workspaceroute-7da4aded72.md); Type: object

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: Search timed out; retry without treating this as an empty result.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/workspace/search' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/workspace/search', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/workspace/search',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List campaigns (paginated)

`GET /v1/my/campaigns`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated campaigns

Content type: application/json

Type: array

Items:
  Reference: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/campaigns?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a campaign

`POST /v1/my/campaigns`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `name` (required)
  Type: string

- `channel` (optional)
  Type: string
  
  default: "email"
  
  enum: ["email","sms"]

Responses:

- 201: Campaign created

Content type: application/json

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "channel": "email"
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "channel": "email"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "channel": "email"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/campaigns',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a campaign

`GET /v1/my/campaigns/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Campaign with trigger, template, and templates

Content type: application/json

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/campaigns/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a campaign

`DELETE /v1/my/campaigns/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted campaign

Content type: application/json

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/campaigns/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/campaigns/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a campaign

`PATCH /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `status` (optional)
  Type: string

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `trigger_attributes` (optional)
  Type: object
  
  - `event` (optional)
    Type: string
  
  - `audience_type` (optional)
    Type: string; nullable
    
    Explicit campaign audience target. Use all_contacts only for deliberate all-subscribed-contact sends.
    
    enum: ["lists","segment","all_contacts"]
  
  - `contact_list_id` (optional)
    Type: integer; nullable
    
    deprecated: true
  
  - `contact_list_ids` (optional)
    Type: array
    
    Items:
      Type: integer
  
  - `segment_id` (optional)
    Type: integer; nullable
  
  - `exclude_segment_ids` (optional)
    Type: array
    
    Segment IDs whose matching contacts are excluded; pass [] to clear
    
    Items:
      Type: integer
  
  - `exclude_contact_list_ids` (optional)
    Type: array
    
    Contact list IDs whose members are excluded; pass [] to clear
    
    Items:
      Type: integer
  
  - `data` (optional)
    Type: object
    
    Additional properties: true

- `template_attributes` (optional)
  Type: object
  
  - `if_version` (required)
    Type: integer
    
    Required optimistic concurrency token for template content writes. Use the current template.version. A stale value returns 409 with current_version and expected_version.
  
  - `subject` (optional)
    Type: string
  
  - `body` (optional)
    Type: string
  
  - `content_format` (optional)
    Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
    
    
    enum: ["designed","plain"]
  
  - `plain_text_mode` (optional)
    Type: string
    
    enum: ["derived","custom"]
  
  - `preheader` (optional)
    Type: string
  
  - `from_name` (optional)
    Type: string
  
  - `from_email` (optional)
    Type: string, email
  
  - `reply_to` (optional)
    Type: string, email
  
  - `generation_provenance` (optional)
    Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
    
  
  - `design` (optional)
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document

Additional properties: false

Responses:

- 200: Updated campaign

Content type: application/json

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- 402: 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.

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `code` (optional)
    Type: integer
    
    const: 402
  
  - `error_code` (required)
    Type: string
    
    enum: ["plan_required"]
  
  - `how_to_fix` (required)
    Type: string
  
  - `plan_url` (required)
    Type: string, uri

- 409: Template version conflict

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/campaigns/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "status": "string",
  "channel": "email",
  "scheduled_at": "2024-01-15T09:30:00Z",
  "trigger_attributes": {
    "event": "string",
    "audience_type": "lists",
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "segment_id": 0,
    "exclude_segment_ids": [
      0
    ],
    "exclude_contact_list_ids": [
      0
    ],
    "data": {}
  },
  "template_attributes": {
    "if_version": 0,
    "subject": "string",
    "body": "string",
    "content_format": "designed",
    "plain_text_mode": "derived",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "generation_provenance": {
      "state": "candidate",
      "event_id": 0,
      "candidate_locator": "string",
      "generated_slice_digest": "string",
      "acceptance_id": 0,
      "saved_authored_digest": "string",
      "edit_relation": "identical"
    },
    "design": {
      "version": 1,
      "sections": [
        {
          "binding": {
            "path": "string",
            "index": 0,
            "limit": 1
          },
          "block": {
            "template_id": 1,
            "key": "string"
          },
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "section_background_color": "string",
            "padding": "string",
            "align": "left",
            "scale": "display",
            "font_size": 0,
            "text_color": "string",
            "shape": "square",
            "remove_gap": true,
            "border_radius": 0
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "heading_size": 0,
        "body_size": 0,
        "radius": 0,
        "spacing_density": "compact",
        "button_background_color": "string",
        "button_text_color": "string",
        "button_padding": "string",
        "logo_url": "string",
        "company_name": "string",
        "physical_address": "string",
        "social_links": [
          {
            "platform": "string",
            "url": "string"
          }
        ]
      }
    }
  }
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "status": "string",
  "channel": "email",
  "scheduled_at": "2024-01-15T09:30:00Z",
  "trigger_attributes": {
    "event": "string",
    "audience_type": "lists",
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "segment_id": 0,
    "exclude_segment_ids": [
      0
    ],
    "exclude_contact_list_ids": [
      0
    ],
    "data": {}
  },
  "template_attributes": {
    "if_version": 0,
    "subject": "string",
    "body": "string",
    "content_format": "designed",
    "plain_text_mode": "derived",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "generation_provenance": {
      "state": "candidate",
      "event_id": 0,
      "candidate_locator": "string",
      "generated_slice_digest": "string",
      "acceptance_id": 0,
      "saved_authored_digest": "string",
      "edit_relation": "identical"
    },
    "design": {
      "version": 1,
      "sections": [
        {
          "binding": {
            "path": "string",
            "index": 0,
            "limit": 1
          },
          "block": {
            "template_id": 1,
            "key": "string"
          },
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "section_background_color": "string",
            "padding": "string",
            "align": "left",
            "scale": "display",
            "font_size": 0,
            "text_color": "string",
            "shape": "square",
            "remove_gap": true,
            "border_radius": 0
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "heading_size": 0,
        "body_size": 0,
        "radius": 0,
        "spacing_density": "compact",
        "button_background_color": "string",
        "button_text_color": "string",
        "button_padding": "string",
        "logo_url": "string",
        "company_name": "string",
        "physical_address": "string",
        "social_links": [
          {
            "platform": "string",
            "url": "string"
          }
        ]
      }
    }
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "status": "string",
  "channel": "email",
  "scheduled_at": "2024-01-15T09:30:00Z",
  "trigger_attributes": {
    "event": "string",
    "audience_type": "lists",
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "segment_id": 0,
    "exclude_segment_ids": [
      0
    ],
    "exclude_contact_list_ids": [
      0
    ],
    "data": {}
  },
  "template_attributes": {
    "if_version": 0,
    "subject": "string",
    "body": "string",
    "content_format": "designed",
    "plain_text_mode": "derived",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "generation_provenance": {
      "state": "candidate",
      "event_id": 0,
      "candidate_locator": "string",
      "generated_slice_digest": "string",
      "acceptance_id": 0,
      "saved_authored_digest": "string",
      "edit_relation": "identical"
    },
    "design": {
      "version": 1,
      "sections": [
        {
          "binding": {
            "path": "string",
            "index": 0,
            "limit": 1
          },
          "block": {
            "template_id": 1,
            "key": "string"
          },
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "section_background_color": "string",
            "padding": "string",
            "align": "left",
            "scale": "display",
            "font_size": 0,
            "text_color": "string",
            "shape": "square",
            "remove_gap": true,
            "border_radius": 0
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "heading_size": 0,
        "body_size": 0,
        "radius": 0,
        "spacing_density": "compact",
        "button_background_color": "string",
        "button_text_color": "string",
        "button_padding": "string",
        "logo_url": "string",
        "company_name": "string",
        "physical_address": "string",
        "social_links": [
          {
            "platform": "string",
            "url": "string"
          }
        ]
      }
    }
  }
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/campaigns/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Duplicate a campaign

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json

Type: object

- `cancel_source` (optional)
  Type: boolean
  
  When true, cancels the source campaign in the same DB transaction as the duplicate creation.
  
  default: false

Responses:

- 201: New draft campaign

Content type: application/json

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns/0/duplicate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "cancel_source": false
}'
```

### JavaScript

```javascript
const body = `{
  "cancel_source": false
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/duplicate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "cancel_source": false
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/campaigns/0/duplicate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Render a campaign email to HTML

`GET /v1/my/campaigns/{id}/render`

Renders the campaign's current template through the shared preview renderer.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Rendered HTML

Content type: application/json

Type: object

- `html` (optional)
  Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns/0/render' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/render', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/campaigns/0/render',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Read saved campaign readiness and capacity guidance

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Structural readiness with optional capacity guidance

Content type: application/json

Type: object

- `ready` (required)
  Type: boolean

- `authority` (required)
  Type: string
  
  const: "structural_readiness_only"

- `note` (required)
  Type: string

- `checks` (required)
  Type: array
  
  Items:
    Type: object
    
    - `name` (required)
      Type: string
    
    - `passed` (required)
      Type: boolean
    
    - `message` (required)
      Type: string
    
    - `audience_count` (optional)
      Type: integer; nullable
      
      minimum: 0
    
    - `from_email` (optional)
      Type: string
      
      Exact From address resolved by the canonical sender resolver.
    
    - `recovery_actions` (optional)
      Type: array
      
      Items:
        Type: object
        
        - `type` (optional)
          Type: string
        
        - `label` (optional)
          Type: string
        
        - `url` (optional)
          Type: string
    
    - `agent_prompt` (optional)
      Type: string
      
      For held or blocked flow emails, each one's fix to paste to an agent, joined.
    
    - `disclosures` (optional)
      Type: array
      
      Each held flow email and its case.
      
      Items:
        Type: object
        
        - `action` (optional)
          Type: string
        
        - `review_id` (optional)
          Type: integer
        
        - `category` (optional)
          Type: string
        
        - `agent_prompt` (optional)
          Type: string

- `blocking_issues` (required)
  Type: array
  
  Items:
    Type: string

- `capacity_recovery` (optional)
  Type: unknown
  
  oneOf:
    Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.
  
    Type: null

- `review_budget` (optional)
  Reference: [DeliveryReviewBudgetStatus](https://docs.nitrosend.com/api/schemas/deliveryreviewbudgetstatus-5de71fba0c.md); Type: 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.

- `versions` (optional)
  Reference: [SubjectVersionOffer](https://docs.nitrosend.com/api/schemas/subjectversionoffer-5077e44038.md); Type: object
  
  Subject line versions for this campaign's audience. Read only.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: 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.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns/0/readiness' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/readiness', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/campaigns/0/readiness',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Ask for suggested alternatives to the subject line

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: The request's state for the current content

Content type: application/json

Type: object

- `status` (required)
  Type: string
  
  enum: ["none","writing","ready","unavailable"]

- `reason` (optional)
  Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns/0/subject_versions' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/subject_versions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/campaigns/0/subject_versions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get current campaign delivery progress

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Current campaign delivery progress

Content type: application/json

Type: object

Schema: [CampaignDeliveryProgress](https://docs.nitrosend.com/api/schemas/campaigndeliveryprogress-34f8b93607.md)

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `stop_reason` (optional)
  Type: string; nullable
  
  Why a stopped send stopped, such as email_under_review for one held by the safety check.

- `safety_review` (optional)
  Type: object; nullable
  
  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.
  
  
  - `how_to_fix` (optional)
    Type: string
  
  - `category` (optional)
    Type: string
  
  - `agent_prompt` (optional)
    Type: string
  
  - `recovery_actions` (optional)
    Type: array
    
    Items:
      Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
  
  - `details` (optional)
    Type: object
    
    For a send it couldn't read, the images and other changes (as SendRefusalDetail details).

- `campaign_send_token` (required)
  Type: string; nullable

- `status` (required)
  Type: string
  
  enum: ["not_started","awaiting_approval","sending","paused","completed","failed","cancelled"]

- `recipients` (required)
  Type: integer
  
  Recipient count captured for the active send.

- `sent` (required)
  Type: integer

- `failed` (required)
  Type: integer

- `pending` (required)
  Type: integer

- `terminal` (required)
  Type: boolean
  
  True when clients can stop polling.

- `poll_after_seconds` (required)
  Type: integer; nullable
  
  Suggested polling delay for active sends.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns/0/delivery' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/delivery', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/campaigns/0/delivery',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Send a test email for a campaign

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `Idempotency-Key` (header, string, required)
  Type: string
  
  maxLength: 128

Request body: application/json

Type: object

- `email` (optional)
  Type: string, email

- `emails` (optional)
  Type: array
  
  Items:
    Type: string, email

- `send_test_to` (optional)
  Type: array
  
  Items:
    Type: string, email

- `contact_id` (optional)
  Type: integer

- `sample_contact_id` (optional)
  Type: integer
  
  Contact whose projected data personalizes the test without changing the test recipient.

- `event_data` (optional)
  Type: object
  
  Sample data for event fields in this test (max 32KB); never records an Event or Order. Campaign products remain fixed, not event-bound.
  
  Additional properties: true

Responses:

- 200: Test email sent

Content type: application/json

Type: object

Schema: [TestSendResult](https://docs.nitrosend.com/api/schemas/testsendresult-9d0d94475b.md)

- `outcome` (optional)
  Type: string
  
  Dispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.
  
  enum: ["sent","partial","pending","held","failed","dry_run","delivered"]

- `sent` (required)
  Type: integer
  
  Number of tests accepted by the sending provider.

- `pending` (optional)
  Type: integer

- `held` (optional)
  Type: integer
  
  Tests awaiting content review; not sent and not automatically replayed after approval.

- `failed` (optional)
  Type: integer

- `dry_run` (optional)
  Type: boolean

- `results` (required)
  Type: array
  
  Items:
    Type: object
    
    - `email` (optional)
      Type: string
    
    - `success` (optional)
      Type: boolean
      
      The sending provider accepted this test; recipient delivery is separate.
    
    - `status` (optional)
      Type: string
      
      held awaits content review and was not sent; delivered is the legacy acceptance label.
      
      enum: ["sent","delivered","pending","held","failed"]
    
    - `code` (optional)
      Type: string
    
    - `message` (optional)
      Type: string
      
      Human-readable dispatch or provider-feedback detail.
    
    - `error` (optional)
      Type: string
      
      Why this recipient's test was not sent.
    
    - `hold_id` (optional)
      Type: integer
      
      Exact content review case for this test.
    
    - `plan_url` (optional)
      Type: string, 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_fix` (optional)
      Type: string
      
      Explicit recovery guidance; approval alone does not send a test.
    
    - `agent_prompt` (optional)
      Type: string
      
      The reason and fix to paste to an agent
    
    - `recovery_actions` (optional)
      Type: array
      
      Items:
        Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
    
    - `details` (optional)
      Type: object
      
      For a test the safety check couldn't read, each image that failed and the other changes to make.
      
      - `images` (optional)
        Type: array
        
        Items:
          Type: object
      
      - `changes` (optional)
        Type: array
        
        Items:
          Type: object
    
    - `message_id` (optional)
      Type: integer
    
    - `provider_id` (optional)
      Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns/0/send_test' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "emails": [
    "user@example.com"
  ],
  "send_test_to": [
    "user@example.com"
  ],
  "contact_id": 0,
  "sample_contact_id": 0,
  "event_data": {}
}'
```

### JavaScript

```javascript
const body = `{
  "email": "user@example.com",
  "emails": [
    "user@example.com"
  ],
  "send_test_to": [
    "user@example.com"
  ],
  "contact_id": 0,
  "sample_contact_id": 0,
  "event_data": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/send_test', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "email": "user@example.com",
  "emails": [
    "user@example.com"
  ],
  "send_test_to": [
    "user@example.com"
  ],
  "contact_id": 0,
  "sample_contact_id": 0,
  "event_data": {}
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/campaigns/0/send_test',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Send a campaign

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json

Type: object

- `expected_campaign_updated_at` (required)
  Type: string, date-time
  
  Exact campaign.updated_at value from the persisted draft being approved for delivery.

- `template_if_version` (required)
  Type: integer
  
  Exact persisted campaign template version being approved for delivery.

- `deliver_at` (optional)
  Type: string, date-time
  
  Future delivery time. Omit for immediate delivery.

- `confirm_send_to_all` (optional)
  Type: boolean
  
  Required when the persisted audience is all_contacts.

- `versions` (optional)
  Type: array
  
  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.
  
  minItems: 1
  
  maxItems: 5
  
  Items:
    Reference: [CampaignVersionInput](https://docs.nitrosend.com/api/schemas/campaignversioninput-c953708c82.md); Type: object

- `winner` (optional)
  Reference: [CampaignWinnerInput](https://docs.nitrosend.com/api/schemas/campaignwinnerinput-cb4e87909a.md); Type: 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.

Responses:

- 200: Campaign sent

Content type: application/json

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- 402: 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.

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `code` (optional)
    Type: integer
    
    const: 402
  
  - `error_code` (required)
    Type: string
    
    enum: ["plan_required"]
  
  - `how_to_fix` (required)
    Type: string
  
  - `plan_url` (required)
    Type: string, uri

- 409: Template version conflict or duplicate send attempt

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns/0/send' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "expected_campaign_updated_at": "2024-01-15T09:30:00Z",
  "template_if_version": 0,
  "deliver_at": "2024-01-15T09:30:00Z",
  "confirm_send_to_all": true,
  "versions": [
    {
      "subject": "string",
      "generation_event_id": 0,
      "candidate_locator": "string"
    }
  ],
  "winner": {
    "test_share_percent": 1,
    "wait_hours": 4,
    "measure": "opens"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "expected_campaign_updated_at": "2024-01-15T09:30:00Z",
  "template_if_version": 0,
  "deliver_at": "2024-01-15T09:30:00Z",
  "confirm_send_to_all": true,
  "versions": [
    {
      "subject": "string",
      "generation_event_id": 0,
      "candidate_locator": "string"
    }
  ],
  "winner": {
    "test_share_percent": 1,
    "wait_hours": 4,
    "measure": "opens"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/0/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "expected_campaign_updated_at": "2024-01-15T09:30:00Z",
  "template_if_version": 0,
  "deliver_at": "2024-01-15T09:30:00Z",
  "confirm_send_to_all": true,
  "versions": [
    {
      "subject": "string",
      "generation_event_id": 0,
      "candidate_locator": "string"
    }
  ],
  "winner": {
    "test_share_percent": 1,
    "wait_hours": 4,
    "measure": "opens"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/campaigns/0/send',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List all templates (paginated)

`GET /v1/my/templates`

Returns a summary view with section counts (not full design).

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 100
  
  maximum: 100

- `scope` (query, string, optional) - Use `standalone` for reusable library templates. Omit or use `all` to retain the complete designed-template result.
  Type: string
  
  default: "all"
  
  enum: ["all","standalone"]

- `include_previews` (query, boolean, optional) - When set, each summary includes rendered preview_html (cached per template version)
  Type: boolean

Responses:

- 200: Template summaries

Content type: application/json

Type: array

Items:
  Reference: [TemplateSummary](https://docs.nitrosend.com/api/schemas/templatesummary-d07df4144e.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/templates?page=1&per=100&scope=all' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/templates?page=1&per=100&scope=all', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/templates?page=1&per=100&scope=all',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a standalone template

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 128

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `subject` (optional)
  Type: string

- `body` (optional)
  Type: string
  
  Author text in plain format; custom text alternative in designed format.

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `preheader` (optional)
  Type: string

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `if_version` (optional)
  Type: integer
  
  Required optimistic concurrency token. Use the current template.version.

- `design` (optional)
  Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
  
  Email template design document

- `catalog_id` (optional)
  Type: string
  
  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.
  

Responses:

- 200: Exact idempotent replay of an existing template

Content type: application/json

Type: object

Schema: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `flow_id` (optional)
  Type: integer; nullable

- `action_id` (optional)
  Type: integer; nullable

- `version` (optional)
  Type: integer

- `subject` (optional)
  Type: string; nullable

- `body` (optional)
  Type: string; nullable

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `block_usage` (optional)
  Type: object
  
  Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.
  
  - `emails` (optional)
    Type: integer
    
    Emails linking it.
  
  - `publishes` (optional)
    Type: integer
    
    Emails in live or paused flows that publish the edit.
  
  - `drafts` (optional)
    Type: integer
    
    Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published
  
  - `unchanged` (optional)
    Type: integer
    
    Emails that keep their content (campaigns no longer unapproved drafts

- `preheader` (optional)
  Type: string; nullable

- `from_name` (optional)
  Type: string; nullable

- `from_email` (optional)
  Type: string; nullable

- `reply_to` (optional)
  Type: string; nullable

- `design` (optional)
  Type: unknown
  
  oneOf:
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document
  
    Type: null

- `variables` (optional)
  Type: object
  
  Additional properties: true

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 201: Created template

Content type: application/json

Type: object

Schema: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `flow_id` (optional)
  Type: integer; nullable

- `action_id` (optional)
  Type: integer; nullable

- `version` (optional)
  Type: integer

- `subject` (optional)
  Type: string; nullable

- `body` (optional)
  Type: string; nullable

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `block_usage` (optional)
  Type: object
  
  Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.
  
  - `emails` (optional)
    Type: integer
    
    Emails linking it.
  
  - `publishes` (optional)
    Type: integer
    
    Emails in live or paused flows that publish the edit.
  
  - `drafts` (optional)
    Type: integer
    
    Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published
  
  - `unchanged` (optional)
    Type: integer
    
    Emails that keep their content (campaigns no longer unapproved drafts

- `preheader` (optional)
  Type: string; nullable

- `from_name` (optional)
  Type: string; nullable

- `from_email` (optional)
  Type: string; nullable

- `reply_to` (optional)
  Type: string; nullable

- `design` (optional)
  Type: unknown
  
  oneOf:
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document
  
    Type: null

- `variables` (optional)
  Type: object
  
  Additional properties: true

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Idempotency-Key reused with changed input

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/templates' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "subject": "string",
  "body": "string",
  "content_format": "designed",
  "plain_text_mode": "derived",
  "preheader": "string",
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "if_version": 0,
  "design": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    }
  },
  "catalog_id": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "subject": "string",
  "body": "string",
  "content_format": "designed",
  "plain_text_mode": "derived",
  "preheader": "string",
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "if_version": 0,
  "design": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    }
  },
  "catalog_id": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/templates', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "subject": "string",
  "body": "string",
  "content_format": "designed",
  "plain_text_mode": "derived",
  "preheader": "string",
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "if_version": 0,
  "design": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    }
  },
  "catalog_id": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/templates',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a template with full design

`GET /v1/my/templates/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Full template including design

Content type: application/json

Type: object

Schema: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `flow_id` (optional)
  Type: integer; nullable

- `action_id` (optional)
  Type: integer; nullable

- `version` (optional)
  Type: integer

- `subject` (optional)
  Type: string; nullable

- `body` (optional)
  Type: string; nullable

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `block_usage` (optional)
  Type: object
  
  Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.
  
  - `emails` (optional)
    Type: integer
    
    Emails linking it.
  
  - `publishes` (optional)
    Type: integer
    
    Emails in live or paused flows that publish the edit.
  
  - `drafts` (optional)
    Type: integer
    
    Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published
  
  - `unchanged` (optional)
    Type: integer
    
    Emails that keep their content (campaigns no longer unapproved drafts

- `preheader` (optional)
  Type: string; nullable

- `from_name` (optional)
  Type: string; nullable

- `from_email` (optional)
  Type: string; nullable

- `reply_to` (optional)
  Type: string; nullable

- `design` (optional)
  Type: unknown
  
  oneOf:
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document
  
    Type: null

- `variables` (optional)
  Type: object
  
  Additional properties: true

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/templates/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/templates/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/templates/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete an unused standalone template

`DELETE /v1/my/templates/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `if_version` (query, integer, required) - Required optimistic concurrency token. Use the current template.version.
  Type: integer

Responses:

- 200: Template deleted

Content type: application/json

Type: object

- `deleted` (required)
  Type: boolean
  
  Example:
  
  ```json
  true
  ```

- `template_id` (required)
  Type: integer

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Template version conflict or deletion blocked by message/flow history

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/templates/0?if_version=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/templates/0?if_version=0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/templates/0?if_version=0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a template

`PATCH /v1/my/templates/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `subject` (optional)
  Type: string

- `body` (optional)
  Type: string

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `preheader` (optional)
  Type: string

- `if_version` (required)
  Type: integer
  
  Required optimistic concurrency token. Use the current template.version. A stale value returns 409 with current_version and expected_version.

- `from_name` (optional)
  Type: string

- `from_email` (optional)
  Type: string, email

- `reply_to` (optional)
  Type: string, email

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `design` (optional)
  Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
  
  Email template design document

Responses:

- 200: Updated template

Content type: application/json

Type: object

Schema: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `flow_id` (optional)
  Type: integer; nullable

- `action_id` (optional)
  Type: integer; nullable

- `version` (optional)
  Type: integer

- `subject` (optional)
  Type: string; nullable

- `body` (optional)
  Type: string; nullable

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `block_usage` (optional)
  Type: object
  
  Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.
  
  - `emails` (optional)
    Type: integer
    
    Emails linking it.
  
  - `publishes` (optional)
    Type: integer
    
    Emails in live or paused flows that publish the edit.
  
  - `drafts` (optional)
    Type: integer
    
    Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published
  
  - `unchanged` (optional)
    Type: integer
    
    Emails that keep their content (campaigns no longer unapproved drafts

- `preheader` (optional)
  Type: string; nullable

- `from_name` (optional)
  Type: string; nullable

- `from_email` (optional)
  Type: string; nullable

- `reply_to` (optional)
  Type: string; nullable

- `design` (optional)
  Type: unknown
  
  oneOf:
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document
  
    Type: null

- `variables` (optional)
  Type: object
  
  Additional properties: true

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 409: Template version conflict

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/templates/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "subject": "string",
  "body": "string",
  "content_format": "designed",
  "plain_text_mode": "derived",
  "preheader": "string",
  "if_version": 0,
  "from_name": "string",
  "from_email": "user@example.com",
  "reply_to": "user@example.com",
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "design": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    }
  }
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "subject": "string",
  "body": "string",
  "content_format": "designed",
  "plain_text_mode": "derived",
  "preheader": "string",
  "if_version": 0,
  "from_name": "string",
  "from_email": "user@example.com",
  "reply_to": "user@example.com",
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "design": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    }
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/templates/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "subject": "string",
  "body": "string",
  "content_format": "designed",
  "plain_text_mode": "derived",
  "preheader": "string",
  "if_version": 0,
  "from_name": "string",
  "from_email": "user@example.com",
  "reply_to": "user@example.com",
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "design": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    }
  }
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/templates/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Render an existing template to HTML

`GET /v1/my/templates/{id}/render`

Renders the template through the shared preview renderer.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Rendered HTML

Content type: application/json

Type: object

- `html` (required)
  Type: string

- `accessibility` (required)
  Reference: [EmailAccessibilityLint](https://docs.nitrosend.com/api/schemas/emailaccessibilitylint-22fefb001e.md); Type: object
  
  Advisory accessibility lint result for rendered email previews

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/templates/0/render' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/templates/0/render', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/templates/0/render',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Send a test email

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `Idempotency-Key` (header, string, required)
  Type: string
  
  maxLength: 128

Request body: application/json

Type: object

- `email` (optional)
  Type: unknown
  
  oneOf:
    Type: string, email
  
    Type: array
    
    Items:
      Type: string, email

- `emails` (optional)
  Type: array
  
  Items:
    Type: string, email

- `send_test_to` (optional)
  Type: array
  
  Items:
    Type: string, email

- `contact_id` (optional)
  Type: integer

- `sample_contact_id` (optional)
  Type: integer
  
  Contact whose projected data personalizes the test without changing the test recipient.

Responses:

- 200: Test email sent

Content type: application/json

Type: object

Schema: [TestSendResult](https://docs.nitrosend.com/api/schemas/testsendresult-9d0d94475b.md)

- `outcome` (optional)
  Type: string
  
  Dispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.
  
  enum: ["sent","partial","pending","held","failed","dry_run","delivered"]

- `sent` (required)
  Type: integer
  
  Number of tests accepted by the sending provider.

- `pending` (optional)
  Type: integer

- `held` (optional)
  Type: integer
  
  Tests awaiting content review; not sent and not automatically replayed after approval.

- `failed` (optional)
  Type: integer

- `dry_run` (optional)
  Type: boolean

- `results` (required)
  Type: array
  
  Items:
    Type: object
    
    - `email` (optional)
      Type: string
    
    - `success` (optional)
      Type: boolean
      
      The sending provider accepted this test; recipient delivery is separate.
    
    - `status` (optional)
      Type: string
      
      held awaits content review and was not sent; delivered is the legacy acceptance label.
      
      enum: ["sent","delivered","pending","held","failed"]
    
    - `code` (optional)
      Type: string
    
    - `message` (optional)
      Type: string
      
      Human-readable dispatch or provider-feedback detail.
    
    - `error` (optional)
      Type: string
      
      Why this recipient's test was not sent.
    
    - `hold_id` (optional)
      Type: integer
      
      Exact content review case for this test.
    
    - `plan_url` (optional)
      Type: string, 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_fix` (optional)
      Type: string
      
      Explicit recovery guidance; approval alone does not send a test.
    
    - `agent_prompt` (optional)
      Type: string
      
      The reason and fix to paste to an agent
    
    - `recovery_actions` (optional)
      Type: array
      
      Items:
        Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
    
    - `details` (optional)
      Type: object
      
      For a test the safety check couldn't read, each image that failed and the other changes to make.
      
      - `images` (optional)
        Type: array
        
        Items:
          Type: object
      
      - `changes` (optional)
        Type: array
        
        Items:
          Type: object
    
    - `message_id` (optional)
      Type: integer
    
    - `provider_id` (optional)
      Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/templates/0/send_test' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "emails": [
    "user@example.com"
  ],
  "send_test_to": [
    "user@example.com"
  ],
  "contact_id": 0,
  "sample_contact_id": 0
}'
```

### JavaScript

```javascript
const body = `{
  "email": "user@example.com",
  "emails": [
    "user@example.com"
  ],
  "send_test_to": [
    "user@example.com"
  ],
  "contact_id": 0,
  "sample_contact_id": 0
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/templates/0/send_test', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "email": "user@example.com",
  "emails": [
    "user@example.com"
  ],
  "send_test_to": [
    "user@example.com"
  ],
  "contact_id": 0,
  "sample_contact_id": 0
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/templates/0/send_test',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Render an email document to HTML

`POST /v1/my/templates/preview`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `event_data` (optional)
  Type: object
  
  Original trigger data used only for this preview (max 32KB).
  
  Additional properties: true

- `document` (required)
  Type: object
  
  Source-free preview preserves the designed default; selecting plain is not accepted.
  
  - `version` (optional)
    Reference: version; Type: integer
    
    minimum: 1
  
  - `sections` (optional)
    Reference: sections; Type: array
  
  - `theme` (optional)
    Reference: theme; Type: object
    
    Theme overrides merged on top of brand theme
  
  - `content_format` (optional)
    Type: string
    
    const: "designed"
  
  Additional properties: false

Responses:

- 200: Rendered HTML

Content type: application/json

Type: object

- `html` (required)
  Type: string

- `accessibility` (required)
  Reference: [EmailAccessibilityLint](https://docs.nitrosend.com/api/schemas/emailaccessibilitylint-22fefb001e.md); Type: object
  
  Advisory accessibility lint result for rendered email previews

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/templates/preview' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "event_data": {},
  "document": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    },
    "content_format": "designed"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "event_data": {},
  "document": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    },
    "content_format": "designed"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/templates/preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "event_data": {},
  "document": {
    "version": 1,
    "sections": [
      {
        "binding": {
          "path": "string",
          "index": 0,
          "limit": 1
        },
        "block": {
          "template_id": 1,
          "key": "string"
        },
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "section_background_color": "string",
          "padding": "string",
          "align": "left",
          "scale": "display",
          "font_size": 0,
          "text_color": "string",
          "shape": "square",
          "remove_gap": true,
          "border_radius": 0
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "heading_size": 0,
      "body_size": 0,
      "radius": 0,
      "spacing_density": "compact",
      "button_background_color": "string",
      "button_text_color": "string",
      "button_padding": "string",
      "logo_url": "string",
      "company_name": "string",
      "physical_address": "string",
      "social_links": [
        {
          "platform": "string",
          "url": "string"
        }
      ]
    },
    "content_format": "designed"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/templates/preview',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get the email component schema

`GET /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Email component schema

Content type: application/json

Type: object

Full schema for email design sections. Each component has type,
description, props (with types, required flags, defaults), and tips.


Schema: [EmailComponentSpec](https://docs.nitrosend.com/api/schemas/emailcomponentspec-39b992201d.md)

- `version` (required)
  Type: integer

- `design_guidelines` (required)
  Type: string

- `renderer_version` (required)
  Type: string
  
  The @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.

- `components` (required)
  Type: array
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
    
    - `description` (required)
      Type: string
    
    - `tips` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `props` (required)
      Type: object
      
      Additional properties: 
        Type: object
        
        - `type` (required)
          Type: string
        
        - `required` (optional)
          Type: boolean
        
        - `default` (optional)
          Type: unknown
        
        - `description` (optional)
          Type: string
        
        - `enum` (optional)
          Type: array
          
          Items:
            Type: string
        
        - `items` (optional)
          Type: object
          
          Additional properties: 
            Type: object
            
            - `type` (required)
              Type: string
            
            - `description` (required)
              Type: string
            
            Additional properties: false
        
        - `server_owned` (optional)
          Type: boolean
        
        - `unset_when_empty` (optional)
          Type: boolean
          
          An empty value is allowed in a draft; delivery leaves the section out.
        
        - `theme_key` (optional)
          Type: string
        
        Additional properties: false
    
    Additional properties: false

- `style_attributes` (required)
  Type: array
  
  Standard per-section style attribute registry.
  
  Items:
    Type: object
    
    - `key` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["color","spacing","enum","number","boolean"]
    
    - `applies_to` (required)
      Type: unknown
    
    - `default` (optional)
      Type: unknown
    
    - `theme_fallback` (optional)
      Type: string
    
    - `description` (required)
      Type: string
    
    - `min` (optional)
      Type: integer
    
    - `max` (optional)
      Type: integer
    
    - `values` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `target` (required)
      Type: object
      
      - `el` (required)
        Type: string
        
        enum: ["section","content","shape"]
      
      - `attr` (optional)
        Type: string
      
      Additional properties: false
    
    Additional properties: false

- `preview_document` (required)
  Type: object
  
  - `parameter` (required)
    Type: string
  
  - `description` (required)
    Type: string
  
  - `example` (required)
    Type: object
    
    Additional properties: true
  
  Additional properties: false

- `variables` (required)
  Type: object
  
  Merge variables grouped by source namespace.
  
  Additional properties: 
    Type: array
    
    Items:
      Type: object
      
      - `name` (required)
        Type: string
      
      - `description` (required)
        Type: string
      
      Additional properties: false

- `filters` (required)
  Type: array
  
  Items:
    Type: object
    
    - `name` (required)
      Type: string
    
    - `syntax` (required)
      Type: string
    
    - `description` (required)
      Type: string
    
    Additional properties: false

- `theme_attributes` (required)
  Type: array
  
  Brand Kit theme attribute registry (single source of truth for the editor).
  
  Items:
    Type: object
    
    - `key` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["color","font","number","enum","spacing","string","image","array"]
    
    - `default` (optional)
      Type: unknown
    
    - `category` (required)
      Type: string
      
      enum: ["color","font","visual_identity","identity"]
    
    - `slot` (optional)
      Type: string
    
    - `surfaces` (required)
      Type: array
      
      Items:
        Type: string
    
    - `min` (optional)
      Type: integer
    
    - `max` (optional)
      Type: integer
    
    - `values` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `options` (optional)
      Type: array
      
      Items:
        Type: object
        
        - `value` (optional)
          Type: string
        
        - `label` (optional)
          Type: string
        
        - `description` (optional)
          Type: string
    
    - `transform_table` (optional)
      Type: object
      
      Additional properties: 
        Type: string
    
    - `column` (optional)
      Type: boolean
    
    - `storage` (optional)
      Type: string
    
    - `placeholder` (optional)
      Type: string
    
    - `value_resolver` (optional)
      Type: string
    
    - `server_owned` (optional)
      Type: boolean
    
    - `description` (optional)
      Type: string
    
    Additional properties: false

Additional properties: false

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/templates/spec' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/templates/spec', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/templates/spec',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List the system template library

`GET /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Library templates with original and brand-matched variants

Content type: application/json

Type: array

Items:
  Reference: [EmailLibraryTemplate](https://docs.nitrosend.com/api/schemas/emaillibrarytemplate-2ea4251cff.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/templates/library' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/templates/library', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/templates/library',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## AI-generate an email draft

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required) - Retry-stable identity for this generation request.
  Type: string
  
  minLength: 1

Request body: application/json (required)

Type: object

- `goal` (required)
  Type: string
  
  What the email should accomplish
  
  Example:
  
  ```json
  "Welcome new subscribers and introduce the brand"
  ```

- `operation` (required)
  Type: string
  
  enum: ["generate","regenerate","refine"]

- `edit_scope` (optional)
  Type: string
  
  Defaults to copy for refine and both otherwise.
  
  enum: ["copy","design","both"]

- `user_instruction` (optional)
  Type: string

- `category` (optional)
  Type: string
  
  Optional category hint (welcome, newsletter, promotion, etc.)

- `tone` (optional)
  Type: string
  
  Optional tone override (formal, casual, etc.)

- `current_draft` (required)
  Type: unknown
  
  Complete unsaved editor state to generate or refine. Supplied format must match the scoped stored/source format; unbound new content defaults to designed.
  
  oneOf:
    Type: object
    
    - `subject` (optional)
      Type: string
    
    - `preheader` (optional)
      Type: string
    
    - `body` (optional)
      Type: string
    
    - `content_format` (optional)
      Type: string
      
      const: "designed"
    
    - `plain_text_mode` (required)
      Type: string
      
      enum: ["derived","custom"]
    
    - `from_name` (optional)
      Type: string
    
    - `from_email` (optional)
      Type: string
    
    - `reply_to` (optional)
      Type: string
    
    - `design` (required)
      Type: object
      
      - `version` (optional)
        Type: integer
      
      - `theme` (optional)
        Type: object
        
        Additional properties: true
      
      - `sections` (required)
        Type: array
        
        Items:
          Type: object
          
          Additional properties: true
      
      Additional properties: true
  
    Type: object
    
    - `content_format` (required)
      Type: string
      
      const: "plain"
    
    - `plain_text_mode` (required)
      Type: string
      
      const: "custom"
    
    - `subject` (optional)
      Type: string
    
    - `preheader` (optional)
      Type: string
    
    - `body` (required)
      Type: string
    
    - `from_name` (optional)
      Type: string
    
    - `from_email` (optional)
      Type: string
    
    - `reply_to` (optional)
      Type: string
    
    - `design` (optional)
      Type: object
      
      Dormant designed content, preserved during plain authoring.
      
      Additional properties: true
  
    Type: object
    
    - `name` (optional)
      Type: string
    
    - `trigger` (required)
      Reference: [FlowTriggerInput](https://docs.nitrosend.com/api/schemas/flowtriggerinput-730691eb66.md); Type: object
    
    - `steps` (required)
      Type: array
      
      Items:
        Reference: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md); Type: object

- `authoring_target` (required)
  Type: unknown
  
  oneOf:
    Type: object
    
    - `surface` (required)
      Type: string
      
      const: "template"
    
    - `template_id` (optional)
      Type: integer
      
      minimum: 1
    
    - `if_version` (optional)
      Type: integer
      
      Required when template_id is present.
      
      minimum: 1
  
    Type: object
    
    - `surface` (required)
      Type: string
      
      const: "campaign"
    
    - `campaign_id` (required)
      Type: integer
      
      minimum: 1
    
    - `template_id` (optional)
      Type: integer
      
      minimum: 1
    
    - `if_version` (required)
      Type: integer
      
      minimum: 1
  
    Type: object
    
    - `surface` (required)
      Type: string
      
      const: "flow"
    
    - `flow_id` (required)
      Type: integer
      
      minimum: 1
    
    - `action_name` (required)
      Type: string
      
      minLength: 1
    
    - `if_version` (required)
      Type: integer
      
      minimum: 1

Responses:

- 200: Generated email design

Content type: application/json

Type: object

- `design` (optional)
  Type: object
  
  { version, theme, sections[] } — ready for GrapesJS

- `subject` (optional)
  Type: string

- `preheader` (optional)
  Type: string

- `body` (optional)
  Type: string

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `category` (optional)
  Type: string
  
  Inferred or provided category

- `prompt_version` (optional)
  Type: string

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `knowledge_used` (optional)
  Type: array
  
  Items:
    Type: string

- 400: Invalid authoring request

Content type: application/json

Type: object

- `code` (required)
  Type: string
  
  enum: ["idempotency_key_required","invalid_authoring_request"]

- `error_code` (required)
  Type: string
  
  enum: ["idempotency_key_required","invalid_authoring_request"]

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- 409: Generation or template version conflict

Content type: application/json

Type: object

- `code` (required)
  Type: string
  
  enum: ["template_version_conflict","idempotency_conflict","generation_in_progress","generation_replay_invalid"]

- `error_code` (required)
  Type: string
  
  enum: ["template_version_conflict","idempotency_conflict","generation_in_progress","generation_replay_invalid"]

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- 422: Validation error

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 429: Rate limit exceeded

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: Generation failed

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/templates/generate' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "goal": "Welcome new subscribers and introduce the brand",
  "operation": "generate",
  "edit_scope": "copy",
  "user_instruction": "string",
  "category": "string",
  "tone": "string",
  "current_draft": {
    "subject": "string",
    "preheader": "string",
    "body": "string",
    "content_format": "designed",
    "plain_text_mode": "derived",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "version": 0,
      "theme": {},
      "sections": [
        {}
      ]
    }
  },
  "authoring_target": {
    "surface": "template",
    "template_id": 1,
    "if_version": 1
  }
}'
```

### JavaScript

```javascript
const body = `{
  "goal": "Welcome new subscribers and introduce the brand",
  "operation": "generate",
  "edit_scope": "copy",
  "user_instruction": "string",
  "category": "string",
  "tone": "string",
  "current_draft": {
    "subject": "string",
    "preheader": "string",
    "body": "string",
    "content_format": "designed",
    "plain_text_mode": "derived",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "version": 0,
      "theme": {},
      "sections": [
        {}
      ]
    }
  },
  "authoring_target": {
    "surface": "template",
    "template_id": 1,
    "if_version": 1
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/templates/generate', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "goal": "Welcome new subscribers and introduce the brand",
  "operation": "generate",
  "edit_scope": "copy",
  "user_instruction": "string",
  "category": "string",
  "tone": "string",
  "current_draft": {
    "subject": "string",
    "preheader": "string",
    "body": "string",
    "content_format": "designed",
    "plain_text_mode": "derived",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "version": 0,
      "theme": {},
      "sections": [
        {}
      ]
    }
  },
  "authoring_target": {
    "surface": "template",
    "template_id": 1,
    "if_version": 1
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/templates/generate',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Save an edited guest flow after sign-in

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required)
  Type: string
  
  maxLength: 128

Request body: application/json (required)

Type: object

- `token` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `name` (optional)
  Type: string

- `send_tests` (optional)
  Type: boolean
  
  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.
  
  
  default: false

- `graph` (required)
  Type: object
  
  - `trigger` (required)
    Type: object
    
    Additional properties: true
  
  - `steps` (required)
    Type: array
    
    Items:
      Type: object
      
      Additional properties: true

Responses:

- 201: Claimed draft flow and target Brand

Content type: application/json

Type: object

- `flow_id` (required)
  Type: integer

- `brand_sid` (required)
  Type: string

- `inbox_tests` (optional)
  Type: string
  
  Present when send_tests was true and the test sends were queued.
  
  enum: ["queued"]

- 409: The same demo was claimed with different input or by another account

- 422: Expired demo, no ready draft for the current revision, invalid graph, or Brand limit reached

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/flow_demo/claim' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "token": "string",
  "name": "string",
  "send_tests": false,
  "graph": {
    "trigger": {},
    "steps": [
      {}
    ]
  }
}'
```

### JavaScript

```javascript
const body = `{
  "token": "string",
  "name": "string",
  "send_tests": false,
  "graph": {
    "trigger": {},
    "steps": [
      {}
    ]
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/flow_demo/claim', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "token": "string",
  "name": "string",
  "send_tests": false,
  "graph": {
    "trigger": {},
    "steps": [
      {}
    ]
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/flow_demo/claim',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Read the selected account's recurring subscription cards

`GET /v1/my/user/payment_method`

Account administrator required. Reads actual provider subscription defaults; never returns payer profile details or changes a shared customer default.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Masked cards by subscription, product_key and plan_name

Content type: application/json

Type: object

- `payment_methods` (optional)
  Type: array
  
  Items:
    Type: object
    
    Additional properties: true

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/user/payment_method' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/user/payment_method', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/user/payment_method',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Replace the card on this account's current plan and paid features

`PUT /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `stripe_token` (required)
  Type: string
  
  writeOnly: true

Responses:

- 200: Confirmed masked cards by account subscription

Content type: application/json

Type: object

- `payment_methods` (optional)
  Type: array
  
  Items:
    Type: object
    
    Additional properties: true

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed, or the card was declined (error_code payment_declined, with a message written for the customer).

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PUT 'https://api.nitrosend.com/v1/my/user/payment_method' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "stripe_token": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "stripe_token": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/user/payment_method', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "stripe_token": "string"
}'''

response = requests.put(
    'https://api.nitrosend.com/v1/my/user/payment_method',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Refuse removal while current recurring terms require payment

`DELETE /v1/my/user/payment_method`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: No recurring account payment method exists

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/user/payment_method' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/user/payment_method', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/user/payment_method',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Open the provider-hosted payment page for an owned unpaid invoice

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Ownership-verified HTTPS Stripe invoice payment URL

Content type: application/json

Type: object

- `payment_url` (optional)
  Type: string, uri

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Invoice does not belong to this account or cannot be paid

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/invoices/0/payment' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/invoices/0/payment', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/invoices/0/payment',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List automation flows (paginated)

`GET /v1/my/flows`

Returns standalone flows only (excludes campaign-attached flows).

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated flows

Content type: application/json

Type: array

Items:
  Reference: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/flows?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flows?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/flows?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a flow

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 128

Request body: application/json (required)

Type: object

- `name` (required)
  Type: string

- `trigger` (optional)
  Reference: [FlowTriggerInput](https://docs.nitrosend.com/api/schemas/flowtriggerinput-730691eb66.md); Type: object

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md); Type: object

Responses:

- 200: Exact idempotent replay of an existing flow

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- 201: Flow created

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Idempotency-Key reused with changed input

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/flows' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "trigger": {
    "stop_on_reply": false,
    "reply_source": {
      "type": "any"
    },
    "exit_events": [
      "string"
    ],
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "data": {}
  },
  "steps": [
    {
      "type": "email",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "description": "string"
        }
      ],
      "branches": {},
      "reply_all": false,
      "cc": [
        "user@example.com"
      ],
      "bcc": [
        "user@example.com"
      ],
      "subject": "string",
      "body": "string",
      "content_format": "designed",
      "plain_text_mode": "derived",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "version": 1,
        "sections": [
          {
            "binding": {
              "path": "string",
              "index": 0,
              "limit": 1
            },
            "block": {
              "template_id": 1,
              "key": "string"
            },
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "section_background_color": "string",
              "padding": "string",
              "align": "left",
              "scale": "display",
              "font_size": 0,
              "text_color": "string",
              "shape": "square",
              "remove_gap": true,
              "border_radius": 0
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "heading_size": 0,
          "body_size": 0,
          "radius": 0,
          "spacing_density": "compact",
          "button_background_color": "string",
          "button_text_color": "string",
          "button_padding": "string",
          "logo_url": "string",
          "company_name": "string",
          "physical_address": "string",
          "social_links": [
            {
              "platform": "string",
              "url": "string"
            }
          ]
        }
      },
      "duration": 0,
      "send_at": "string",
      "time_zone": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ],
      "yes": [],
      "no": [],
      "event_name": "string",
      "forward_event_data": false,
      "event_data": {},
      "transactional": false
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "trigger": {
    "stop_on_reply": false,
    "reply_source": {
      "type": "any"
    },
    "exit_events": [
      "string"
    ],
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "data": {}
  },
  "steps": [
    {
      "type": "email",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "description": "string"
        }
      ],
      "branches": {},
      "reply_all": false,
      "cc": [
        "user@example.com"
      ],
      "bcc": [
        "user@example.com"
      ],
      "subject": "string",
      "body": "string",
      "content_format": "designed",
      "plain_text_mode": "derived",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "version": 1,
        "sections": [
          {
            "binding": {
              "path": "string",
              "index": 0,
              "limit": 1
            },
            "block": {
              "template_id": 1,
              "key": "string"
            },
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "section_background_color": "string",
              "padding": "string",
              "align": "left",
              "scale": "display",
              "font_size": 0,
              "text_color": "string",
              "shape": "square",
              "remove_gap": true,
              "border_radius": 0
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "heading_size": 0,
          "body_size": 0,
          "radius": 0,
          "spacing_density": "compact",
          "button_background_color": "string",
          "button_text_color": "string",
          "button_padding": "string",
          "logo_url": "string",
          "company_name": "string",
          "physical_address": "string",
          "social_links": [
            {
              "platform": "string",
              "url": "string"
            }
          ]
        }
      },
      "duration": 0,
      "send_at": "string",
      "time_zone": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ],
      "yes": [],
      "no": [],
      "event_name": "string",
      "forward_event_data": false,
      "event_data": {},
      "transactional": false
    }
  ]
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/flows', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "trigger": {
    "stop_on_reply": false,
    "reply_source": {
      "type": "any"
    },
    "exit_events": [
      "string"
    ],
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "data": {}
  },
  "steps": [
    {
      "type": "email",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "description": "string"
        }
      ],
      "branches": {},
      "reply_all": false,
      "cc": [
        "user@example.com"
      ],
      "bcc": [
        "user@example.com"
      ],
      "subject": "string",
      "body": "string",
      "content_format": "designed",
      "plain_text_mode": "derived",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "version": 1,
        "sections": [
          {
            "binding": {
              "path": "string",
              "index": 0,
              "limit": 1
            },
            "block": {
              "template_id": 1,
              "key": "string"
            },
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "section_background_color": "string",
              "padding": "string",
              "align": "left",
              "scale": "display",
              "font_size": 0,
              "text_color": "string",
              "shape": "square",
              "remove_gap": true,
              "border_radius": 0
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "heading_size": 0,
          "body_size": 0,
          "radius": 0,
          "spacing_density": "compact",
          "button_background_color": "string",
          "button_text_color": "string",
          "button_padding": "string",
          "logo_url": "string",
          "company_name": "string",
          "physical_address": "string",
          "social_links": [
            {
              "platform": "string",
              "url": "string"
            }
          ]
        }
      },
      "duration": 0,
      "send_at": "string",
      "time_zone": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ],
      "yes": [],
      "no": [],
      "event_name": "string",
      "forward_event_data": false,
      "event_data": {},
      "transactional": false
    }
  ]
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/flows',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Write a draft flow for the brand from a goal or a template

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 128

Request body: application/json (required)

Type: object

- `goal` (optional)
  Type: string
  
  minLength: 1
  
  maxLength: 1000

- `template_id` (optional)
  Type: string
  
  A flow template id, sent instead of goal.

- `contact_list_id` (optional)
  Type: integer
  
  The brand list a list_add template starts on.

Responses:

- 200: Exact idempotent replay of an existing flow

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- 201: Flow written and saved as a draft

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The first request with this key is still writing, or the key was reused with a changed request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

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


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: Planning or writing failed; retry with the same key

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/flows/generate' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "goal": "string",
  "template_id": "string",
  "contact_list_id": 0
}'
```

### JavaScript

```javascript
const body = `{
  "goal": "string",
  "template_id": "string",
  "contact_list_id": 0
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/flows/generate', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "goal": "string",
  "template_id": "string",
  "contact_list_id": 0
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/flows/generate',
    data=body.encode('utf-8'),
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a flow

`GET /v1/my/flows/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `include_blockers` (query, boolean, optional) - Pass `false` to leave `blockers` out of `unpublished_change`, as
the flow list does, which skips the publish checks. Defaults to
`true`.

  Type: boolean
  
  default: true

Responses:

- 200: Flow with full graph

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/flows/0?include_blockers=true' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flows/0?include_blockers=true', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/flows/0?include_blockers=true',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a flow

`DELETE /v1/my/flows/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted flow

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/flows/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flows/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/flows/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a flow

`PATCH /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string
  
  enum: ["approved","rejected"]

- `revision_id` (optional)
  Type: integer; nullable
  
  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_mode` (optional)
  Type: string
  
  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.
  
  enum: ["new_contacts_only","continue_existing"]

- `expected_draft_revision_id` (optional)
  Type: integer; nullable
  
  Exact optimistic concurrency token for authored graph changes.

- `updated_at` (optional)
  Type: string, date-time
  
  Optimistic concurrency check

- `trigger` (optional)
  Reference: [FlowTriggerInput](https://docs.nitrosend.com/api/schemas/flowtriggerinput-730691eb66.md); Type: object

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md); Type: object

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `publish` (optional)
  Type: boolean
  
  With an authoring save to a live or paused flow, publish the saved revision. Ignored without authoring fields.
  
  default: false

Responses:

- 200: Updated flow

Content type: application/json

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- 402: 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.

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `code` (optional)
    Type: integer
    
    const: 402
  
  - `error_code` (required)
    Type: string
    
    enum: ["plan_required"]
  
  - `how_to_fix` (required)
    Type: string
  
  - `plan_url` (required)
    Type: string, uri

- 409: Conflict — the authored draft or requested publication revision is stale

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: 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.


Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string
  
  - `how_to_fix` (optional)
    Type: string
  
  - `recovery_actions` (optional)
    Type: array
    
    Items:
      Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
  
  - `agent_prompt` (optional)
    Type: string
    
    For held or blocked flow emails, each one's fix to paste to an agent, joined.
  
  - `disclosures` (optional)
    Type: array
    
    Each held flow email and its case.
    
    Items:
      Type: object
      
      - `action` (optional)
        Type: string
      
      - `review_id` (optional)
        Type: integer
      
      - `category` (optional)
        Type: string
      
      - `agent_prompt` (optional)
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/flows/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "status": "draft",
  "approval_state": "approved",
  "revision_id": 0,
  "resume_mode": "new_contacts_only",
  "expected_draft_revision_id": 0,
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "stop_on_reply": false,
    "reply_source": {
      "type": "any"
    },
    "exit_events": [
      "string"
    ],
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "data": {}
  },
  "steps": [
    {
      "type": "email",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "description": "string"
        }
      ],
      "branches": {},
      "reply_all": false,
      "cc": [
        "user@example.com"
      ],
      "bcc": [
        "user@example.com"
      ],
      "subject": "string",
      "body": "string",
      "content_format": "designed",
      "plain_text_mode": "derived",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "version": 1,
        "sections": [
          {
            "binding": {
              "path": "string",
              "index": 0,
              "limit": 1
            },
            "block": {
              "template_id": 1,
              "key": "string"
            },
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "section_background_color": "string",
              "padding": "string",
              "align": "left",
              "scale": "display",
              "font_size": 0,
              "text_color": "string",
              "shape": "square",
              "remove_gap": true,
              "border_radius": 0
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "heading_size": 0,
          "body_size": 0,
          "radius": 0,
          "spacing_density": "compact",
          "button_background_color": "string",
          "button_text_color": "string",
          "button_padding": "string",
          "logo_url": "string",
          "company_name": "string",
          "physical_address": "string",
          "social_links": [
            {
              "platform": "string",
              "url": "string"
            }
          ]
        }
      },
      "duration": 0,
      "send_at": "string",
      "time_zone": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ],
      "yes": [],
      "no": [],
      "event_name": "string",
      "forward_event_data": false,
      "event_data": {},
      "transactional": false
    }
  ],
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "publish": false
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "status": "draft",
  "approval_state": "approved",
  "revision_id": 0,
  "resume_mode": "new_contacts_only",
  "expected_draft_revision_id": 0,
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "stop_on_reply": false,
    "reply_source": {
      "type": "any"
    },
    "exit_events": [
      "string"
    ],
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "data": {}
  },
  "steps": [
    {
      "type": "email",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "description": "string"
        }
      ],
      "branches": {},
      "reply_all": false,
      "cc": [
        "user@example.com"
      ],
      "bcc": [
        "user@example.com"
      ],
      "subject": "string",
      "body": "string",
      "content_format": "designed",
      "plain_text_mode": "derived",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "version": 1,
        "sections": [
          {
            "binding": {
              "path": "string",
              "index": 0,
              "limit": 1
            },
            "block": {
              "template_id": 1,
              "key": "string"
            },
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "section_background_color": "string",
              "padding": "string",
              "align": "left",
              "scale": "display",
              "font_size": 0,
              "text_color": "string",
              "shape": "square",
              "remove_gap": true,
              "border_radius": 0
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "heading_size": 0,
          "body_size": 0,
          "radius": 0,
          "spacing_density": "compact",
          "button_background_color": "string",
          "button_text_color": "string",
          "button_padding": "string",
          "logo_url": "string",
          "company_name": "string",
          "physical_address": "string",
          "social_links": [
            {
              "platform": "string",
              "url": "string"
            }
          ]
        }
      },
      "duration": 0,
      "send_at": "string",
      "time_zone": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ],
      "yes": [],
      "no": [],
      "event_name": "string",
      "forward_event_data": false,
      "event_data": {},
      "transactional": false
    }
  ],
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "publish": false
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/flows/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "status": "draft",
  "approval_state": "approved",
  "revision_id": 0,
  "resume_mode": "new_contacts_only",
  "expected_draft_revision_id": 0,
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "stop_on_reply": false,
    "reply_source": {
      "type": "any"
    },
    "exit_events": [
      "string"
    ],
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "exclude_segment_ids": [
      0
    ],
    "data": {}
  },
  "steps": [
    {
      "type": "email",
      "categories": [
        {
          "key": "string",
          "label": "string",
          "description": "string"
        }
      ],
      "branches": {},
      "reply_all": false,
      "cc": [
        "user@example.com"
      ],
      "bcc": [
        "user@example.com"
      ],
      "subject": "string",
      "body": "string",
      "content_format": "designed",
      "plain_text_mode": "derived",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "version": 1,
        "sections": [
          {
            "binding": {
              "path": "string",
              "index": 0,
              "limit": 1
            },
            "block": {
              "template_id": 1,
              "key": "string"
            },
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "section_background_color": "string",
              "padding": "string",
              "align": "left",
              "scale": "display",
              "font_size": 0,
              "text_color": "string",
              "shape": "square",
              "remove_gap": true,
              "border_radius": 0
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "heading_size": 0,
          "body_size": 0,
          "radius": 0,
          "spacing_density": "compact",
          "button_background_color": "string",
          "button_text_color": "string",
          "button_padding": "string",
          "logo_url": "string",
          "company_name": "string",
          "physical_address": "string",
          "social_links": [
            {
              "platform": "string",
              "url": "string"
            }
          ]
        }
      },
      "duration": 0,
      "send_at": "string",
      "time_zone": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ],
      "yes": [],
      "no": [],
      "event_name": "string",
      "forward_event_data": false,
      "event_data": {},
      "transactional": false
    }
  ],
  "generation_provenance": {
    "state": "candidate",
    "event_id": 0,
    "candidate_locator": "string",
    "generated_slice_digest": "string",
    "acceptance_id": 0,
    "saved_authored_digest": "string",
    "edit_relation": "identical"
  },
  "publish": false
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/flows/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Preview the choices for restarting a paused flow

`GET /v1/my/flows/{id}/resume_plan`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Current restart impact and available choices

Content type: application/json

Type: object

Schema: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md)

- `flow_id` (required)
  Type: integer

- `status` (required)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `open_journey_count` (required)
  Type: integer
  
  minimum: 0

- `contact_count` (required)
  Type: integer
  
  minimum: 0

- `waiting_journey_count` (required)
  Type: integer
  
  minimum: 0

- `scheduled_journey_count` (required)
  Type: integer
  
  minimum: 0

- `has_unpublished_changes` (required)
  Type: boolean

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `requires_choice` (required)
  Type: boolean

- `allowed_modes` (required)
  Type: array
  
  Items:
    Type: string
    
    enum: ["new_contacts_only","continue_existing"]

- `recommended_mode` (required)
  Type: string
  
  enum: ["new_contacts_only"]

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/flows/0/resume_plan' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flows/0/resume_plan', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/flows/0/resume_plan',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get the flow step type schema

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Flow specification

Content type: application/json

Type: 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.


Schema: [FlowSpec](https://docs.nitrosend.com/api/schemas/flowspec-bdd31bc61e.md)

- `filters` (optional)
  Reference: filters; Type: object

- `triggers` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `title` (optional)
      Type: string
    
    - `event` (optional)
      Type: string
    
    - `description` (optional)
      Type: string
      
      What fires the trigger.
    
    - `variables` (optional)
      Type: object
      
      - `paths` (optional)
        Type: array
        
        Items:
          Type: object
          
          - `path` (optional)
            Type: string
            
            Declared event payload path.
          
          - `type` (optional)
            Type: string
            
            enum: ["string","integer","number","boolean","object","array"]
      
      - `filters` (optional)
        Reference: filters; Type: object

- `filter_limits` (optional)
  Type: object
  
  Limits every filter tree is held to on save. A tree past either limit is refused with invalid_filter.
  
  - `max_depth` (optional)
    Type: integer
    
    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_group` (optional)
    Type: integer
    
    The most conditions one group may hold.

- `steps` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `type` (optional)
      Type: string
    
    - `title` (optional)
      Type: string
    
    - `summary` (optional)
      Type: string
    
    - `params` (optional)
      Type: object
      
      Additional properties: 
        Type: object
        
        - `label` (optional)
          Type: string
        
        - `type` (optional)
          Type: string
        
        - `required` (optional)
          Type: boolean
        
        - `default` (optional)
          Type: unknown
        
        - `description` (optional)
          Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/flows/spec' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flows/spec', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/flows/spec',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Review a campaign send that waits for the account owner's approval

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: The send approval

Content type: application/json

Type: object

Schema: [SendApproval](https://docs.nitrosend.com/api/schemas/sendapproval-9ba478f173.md)

- `id` (required)
  Type: integer

- `campaign_id` (required)
  Type: integer

- `can_decide` (required)
  Type: boolean
  
  Whether the signed-in person may decide it, as the account owner or a direct account admin.

- `state` (required)
  Type: string
  
  `withdrawn` means the send stopped before anyone decided. After approval, `delivery_status` tells a send in progress from a finished one.
  
  
  enum: ["pending","approved","declined","expired","withdrawn"]

- `decided_at` (optional)
  Type: string, date-time

- `delivery_status` (required)
  Type: string
  
  enum: ["pending","in_progress","completed","failed","cancelled"]

- `content` (required)
  Type: object
  
  - `subject` (required)
    Type: string
  
  - `preheader` (optional)
    Type: string
  
  - `html` (required)
    Type: string
    
    The exact email the approval sends.
  
  Additional properties: false

- `bcc` (optional)
  Type: string
  
  The address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.

- `mail_action` (required)
  Reference: [MailActionDescription](https://docs.nitrosend.com/api/schemas/mailactiondescription-e8c6bf32cc.md); Type: object
  
  The Campaign Send Approval 0.1 description of this send's exact terms.

Additional properties: false

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/map/approvals/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/map/approvals/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/map/approvals/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Approve or decline a held campaign send at its terms version

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `decision` (required)
  Type: string
  
  enum: ["approve","decline"]

- `version` (required)
  Type: string
  
  The terms version the decision was made on.

Additional properties: false

Responses:

- 200: The send approval after the decision

Content type: application/json

Type: object

Schema: [SendApproval](https://docs.nitrosend.com/api/schemas/sendapproval-9ba478f173.md)

- `id` (required)
  Type: integer

- `campaign_id` (required)
  Type: integer

- `can_decide` (required)
  Type: boolean
  
  Whether the signed-in person may decide it, as the account owner or a direct account admin.

- `state` (required)
  Type: string
  
  `withdrawn` means the send stopped before anyone decided. After approval, `delivery_status` tells a send in progress from a finished one.
  
  
  enum: ["pending","approved","declined","expired","withdrawn"]

- `decided_at` (optional)
  Type: string, date-time

- `delivery_status` (required)
  Type: string
  
  enum: ["pending","in_progress","completed","failed","cancelled"]

- `content` (required)
  Type: object
  
  - `subject` (required)
    Type: string
  
  - `preheader` (optional)
    Type: string
  
  - `html` (required)
    Type: string
    
    The exact email the approval sends.
  
  Additional properties: false

- `bcc` (optional)
  Type: string
  
  The address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.

- `mail_action` (required)
  Reference: [MailActionDescription](https://docs.nitrosend.com/api/schemas/mailactiondescription-e8c6bf32cc.md); Type: object
  
  The Campaign Send Approval 0.1 description of this send's exact terms.

Additional properties: false

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 402: 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.

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `code` (optional)
    Type: integer
    
    const: 402
  
  - `error_code` (required)
    Type: string
    
    enum: ["plan_required"]
  
  - `how_to_fix` (required)
    Type: string
  
  - `plan_url` (required)
    Type: string, uri

- 403: 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.


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The send was already decided, changed since the given version, expired or was withdrawn. Nothing is applied.


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/map/approvals/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "decision": "approve",
  "version": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "decision": "approve",
  "version": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/map/approvals/0', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "decision": "approve",
  "version": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/map/approvals/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List flow templates

`GET /v1/my/flow_templates`

Returns the gallery templates available to the current account's enabled
capabilities. Filter the available templates with `category`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `category` (query, string, optional) - Return only this category's available templates, such as `ecommerce`.
  Type: string

Responses:

- 200: List of flow templates

Content type: application/json

Type: array

Items:
  Reference: [FlowTemplate](https://docs.nitrosend.com/api/schemas/flowtemplate-f707a80e4c.md); Type: object
  
  Lean flow template card for index listings.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/flow_templates' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flow_templates', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/flow_templates',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get a flow template

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Flow template slug (e.g. `welcome`)
  Type: string

Responses:

- 200: Flow template with full graph

Content type: application/json

Type: FlowTemplateDetail

Schema: [FlowTemplateDetail](https://docs.nitrosend.com/api/schemas/flowtemplatedetail-7a33615694.md)

allOf:
  Reference: [FlowTemplate](https://docs.nitrosend.com/api/schemas/flowtemplate-f707a80e4c.md); Type: object
  
  Lean flow template card for index listings.

  Type: object
  
  Full flow template including the graph, ready for POST /v1/my/flows.
  
  - `trigger` (optional)
    Type: object
    
    Trigger definition (pass as-is to POST /v1/my/flows trigger param)
    
    Additional properties: true
  
  - `steps` (optional)
    Type: array
    
    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`.
    
    
    Items:
      Type: object
      
      Additional properties: true

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/flow_templates/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/flow_templates/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/flow_templates/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List events (paginated)

`GET /v1/my/events`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 50
  
  maximum: 100

- `event` (query, string, optional) - Filter by event type
  Type: string

- `contact_id` (query, integer, optional)
  Type: integer

- `created_after` (query, string, date-time, optional)
  Type: string, date-time

- `created_before` (query, string, date-time, optional)
  Type: string, date-time

- `resource_uid` (query, string, optional)
  Type: string

- `resource_name` (query, string, optional)
  Type: string

- `test` (query, boolean, optional)
  Type: boolean

Responses:

- 200: Paginated events

Content type: application/json

Type: array

Items:
  Reference: [Event](https://docs.nitrosend.com/api/schemas/event-4e1f49a9c8.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/events?page=1&limit=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/events?page=1&limit=50', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/events?page=1&limit=50',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Track a contact event

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, optional) - Idempotency key (alternative to body param)
  Type: string
  
  maxLength: 128

Request body: application/json (required)

Type: object

- `event` (required)
  Type: string
  
  Event type name (lowercase, underscores)
  
  pattern: "^[a-z][a-z0-9_]{0,63}$"

- `contact_id` (optional)
  Type: integer

- `contact_email` (optional)
  Type: string, 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_key` (optional)
  Type: string
  
  Idempotency key (alternative to header)
  
  maxLength: 128

- `amount` (optional)
  Type: number, double

- `resource_uid` (optional)
  Type: string

- `resource_name` (optional)
  Type: string

- `resource_url` (optional)
  Type: string, uri

- `test` (optional)
  Type: boolean
  
  default: false

- `data` (optional)
  Type: object
  
  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.
  
  Additional properties: true

- `utm_source` (optional)
  Type: string

- `utm_medium` (optional)
  Type: string

- `utm_term` (optional)
  Type: string

- `utm_content` (optional)
  Type: string

- `utm_campaign` (optional)
  Type: string

Responses:

- 200: Duplicate event (idempotent — returns existing)

Content type: application/json

Type: object

Schema: [Event](https://docs.nitrosend.com/api/schemas/event-4e1f49a9c8.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `contact_id` (optional)
  Type: integer

- `user_id` (optional)
  Type: integer

- `event` (optional)
  Type: string

- `amount` (optional)
  Type: number, double; nullable

- `data` (optional)
  Type: object
  
  Additional properties: true

- `idempotency_key` (optional)
  Type: string; nullable

- `resource_uid` (optional)
  Type: string; nullable

- `resource_name` (optional)
  Type: string; nullable

- `resource_url` (optional)
  Type: string; nullable

- `test` (optional)
  Type: boolean

- `generated` (optional)
  Type: boolean

- `chain_depth` (optional)
  Type: integer

- `ip` (optional)
  Type: string; nullable

- `user_agent` (optional)
  Type: string; nullable

- `browser` (optional)
  Type: string; nullable

- `os` (optional)
  Type: string; nullable

- `device_type` (optional)
  Type: string; nullable

- `referrer` (optional)
  Type: string; nullable

- `utm_source` (optional)
  Type: string; nullable

- `utm_medium` (optional)
  Type: string; nullable

- `utm_term` (optional)
  Type: string; nullable

- `utm_content` (optional)
  Type: string; nullable

- `utm_campaign` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 201: Event created

Content type: application/json

Type: object

Schema: [Event](https://docs.nitrosend.com/api/schemas/event-4e1f49a9c8.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `contact_id` (optional)
  Type: integer

- `user_id` (optional)
  Type: integer

- `event` (optional)
  Type: string

- `amount` (optional)
  Type: number, double; nullable

- `data` (optional)
  Type: object
  
  Additional properties: true

- `idempotency_key` (optional)
  Type: string; nullable

- `resource_uid` (optional)
  Type: string; nullable

- `resource_name` (optional)
  Type: string; nullable

- `resource_url` (optional)
  Type: string; nullable

- `test` (optional)
  Type: boolean

- `generated` (optional)
  Type: boolean

- `chain_depth` (optional)
  Type: integer

- `ip` (optional)
  Type: string; nullable

- `user_agent` (optional)
  Type: string; nullable

- `browser` (optional)
  Type: string; nullable

- `os` (optional)
  Type: string; nullable

- `device_type` (optional)
  Type: string; nullable

- `referrer` (optional)
  Type: string; nullable

- `utm_source` (optional)
  Type: string; nullable

- `utm_medium` (optional)
  Type: string; nullable

- `utm_term` (optional)
  Type: string; nullable

- `utm_content` (optional)
  Type: string; nullable

- `utm_campaign` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The correction's order has not arrived. Retry after recording the purchase, using the same idempotency key; no event or phantom order is created.

Content type: application/json

Type: object

- `code` (optional)
  Type: integer
  
  const: 409

- `error` (optional)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string
  
  const: "order_not_recorded"

- `retryable` (optional)
  Type: boolean
  
  const: true

- `message` (optional)
  Type: string

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/events' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "event": "string",
  "contact_id": 0,
  "contact_email": "user@example.com",
  "idempotency_key": "string",
  "amount": 0,
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "https://example.com",
  "test": false,
  "data": {},
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "event": "string",
  "contact_id": 0,
  "contact_email": "user@example.com",
  "idempotency_key": "string",
  "amount": 0,
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "https://example.com",
  "test": false,
  "data": {},
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "event": "string",
  "contact_id": 0,
  "contact_email": "user@example.com",
  "idempotency_key": "string",
  "amount": 0,
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "https://example.com",
  "test": false,
  "data": {},
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/events',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List event names for filter autocomplete

`GET /v1/my/events/names`

Returns known platform event names plus observed event names for the current brand.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Event name suggestions

Content type: application/json

Type: object

- `names` (optional)
  Type: array
  
  Items:
    Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/events/names' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/events/names', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/events/names',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get an event

`GET /v1/my/events/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Event

Content type: application/json

Type: object

Schema: [Event](https://docs.nitrosend.com/api/schemas/event-4e1f49a9c8.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `contact_id` (optional)
  Type: integer

- `user_id` (optional)
  Type: integer

- `event` (optional)
  Type: string

- `amount` (optional)
  Type: number, double; nullable

- `data` (optional)
  Type: object
  
  Additional properties: true

- `idempotency_key` (optional)
  Type: string; nullable

- `resource_uid` (optional)
  Type: string; nullable

- `resource_name` (optional)
  Type: string; nullable

- `resource_url` (optional)
  Type: string; nullable

- `test` (optional)
  Type: boolean

- `generated` (optional)
  Type: boolean

- `chain_depth` (optional)
  Type: integer

- `ip` (optional)
  Type: string; nullable

- `user_agent` (optional)
  Type: string; nullable

- `browser` (optional)
  Type: string; nullable

- `os` (optional)
  Type: string; nullable

- `device_type` (optional)
  Type: string; nullable

- `referrer` (optional)
  Type: string; nullable

- `utm_source` (optional)
  Type: string; nullable

- `utm_medium` (optional)
  Type: string; nullable

- `utm_term` (optional)
  Type: string; nullable

- `utm_content` (optional)
  Type: string; nullable

- `utm_campaign` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/events/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/events/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/events/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete an event

`DELETE /v1/my/events/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Deleted event

Content type: application/json

Type: object

Schema: [Event](https://docs.nitrosend.com/api/schemas/event-4e1f49a9c8.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `contact_id` (optional)
  Type: integer

- `user_id` (optional)
  Type: integer

- `event` (optional)
  Type: string

- `amount` (optional)
  Type: number, double; nullable

- `data` (optional)
  Type: object
  
  Additional properties: true

- `idempotency_key` (optional)
  Type: string; nullable

- `resource_uid` (optional)
  Type: string; nullable

- `resource_name` (optional)
  Type: string; nullable

- `resource_url` (optional)
  Type: string; nullable

- `test` (optional)
  Type: boolean

- `generated` (optional)
  Type: boolean

- `chain_depth` (optional)
  Type: integer

- `ip` (optional)
  Type: string; nullable

- `user_agent` (optional)
  Type: string; nullable

- `browser` (optional)
  Type: string; nullable

- `os` (optional)
  Type: string; nullable

- `device_type` (optional)
  Type: string; nullable

- `referrer` (optional)
  Type: string; nullable

- `utm_source` (optional)
  Type: string; nullable

- `utm_medium` (optional)
  Type: string; nullable

- `utm_term` (optional)
  Type: string; nullable

- `utm_content` (optional)
  Type: string; nullable

- `utm_campaign` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/events/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/events/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/events/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List sending domains (paginated)

`GET /v1/my/domains`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 30
  
  maximum: 100

Responses:

- 200: Paginated domains

Content type: application/json

Type: array

Items:
  Reference: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/domains?page=1&per=30' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/domains?page=1&per=30', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/domains?page=1&per=30',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Add a sending domain

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `domain` (required)
  Type: object
  
  - `name` (required)
    Type: string
    
    e.g. send.example.com

Responses:

- 201: Domain registered with DNS records to configure

Content type: application/json

Type: object

Schema: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `provider` (optional)
  Type: string
  
  default: "ses"

- `default_from_domain` (optional)
  Type: string
  
  Domain Nitrosend will use for visible From addresses when this sending domain is selected.

- `subdomain_sharing_available` (optional)
  Type: boolean
  
  The current principal can manage sharing on this verified apex.

- `shared_subdomain` (optional)
  Type: object
  
  Present only for a shared child, including after permission ends. DNS status is independent.
  
  - `active` (optional)
    Type: boolean
  
  - `parent_domain` (optional)
    Type: string; nullable
  
  - `message` (optional)
    Type: string; nullable

- `sender_authorization_reason` (optional)
  Type: string
  
  Machine-readable reason the default visible From domain is or is not authorized.
  
  enum: ["missing_sender_domain","exact_inbox","exact_mailbox","shared_domain_requires_exact_inbox","shared_domain_not_verified","platform_domain","sender_domain_not_authorized","sending_domain","unaligned_apex_supported","author_identity_not_verified","author_domain_unaligned","author_domain","sender_domain_mismatch"]

- `outstanding` (optional)
  Type: object; nullable
  
  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.
  
  - `code` (required)
    Type: string
    
    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.
    
    enum: ["dns_records","provider_confirmation","domain_review","domain_permission"]
  
  - `action_required` (required)
    Type: boolean
    
    True when the customer has to act; false when the domain verifies on its own.
  
  - `items` (required)
    Type: array
    
    The DNS records or provider checks still outstanding, per domain.
    
    Items:
      Type: object
      
      - `domain` (required)
        Type: string
        
        The sending domain or its From domain.
      
      - `check` (required)
        Type: string
        
        A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).
  
  - `message` (required)
    Type: string
    
    Customer-facing explanation
  
  - `next_check_at` (required)
    Type: string, date-time; nullable
    
    When Nitrosend next checks this domain automatically; null when nothing is scheduled.

- `integration_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["pending","verified"]

- `dmarc_policy` (optional)
  Type: string
  
  Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
  
  enum: ["none","quarantine","reject"]

- `dmarc_recommended_policy` (optional)
  Type: string
  
  Nitrosend's recommended DMARC policy rung.
  
  enum: ["none","quarantine","reject"]

- `dmarc_observed_policy` (optional)
  Type: string; nullable
  
  Last live DMARC policy observed by Nitrosend.
  
  enum: ["none","quarantine","reject"]

- `dns_records` (optional)
  Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object; nullable

- `inbound_setup` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md); Type: object

- `dns_health` (optional)
  Type: object; nullable
  
  Additional properties: true

- `dns_setup_status` (optional)
  Type: string
  
  enum: ["unchecked","incomplete","ready","verified"]

- `verified_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 503: 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.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/domains' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "domain": {
    "name": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "domain": {
    "name": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/domains', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "domain": {
    "name": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/domains',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a domain with DNS records and status

`GET /v1/my/domains/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `inbox_id` (query, integer, optional) - Select one of this domain's inboxes for receiving setup and forwarding status.
  Type: integer

Responses:

- 200: Domain

Content type: application/json

Type: object

Schema: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `provider` (optional)
  Type: string
  
  default: "ses"

- `default_from_domain` (optional)
  Type: string
  
  Domain Nitrosend will use for visible From addresses when this sending domain is selected.

- `subdomain_sharing_available` (optional)
  Type: boolean
  
  The current principal can manage sharing on this verified apex.

- `shared_subdomain` (optional)
  Type: object
  
  Present only for a shared child, including after permission ends. DNS status is independent.
  
  - `active` (optional)
    Type: boolean
  
  - `parent_domain` (optional)
    Type: string; nullable
  
  - `message` (optional)
    Type: string; nullable

- `sender_authorization_reason` (optional)
  Type: string
  
  Machine-readable reason the default visible From domain is or is not authorized.
  
  enum: ["missing_sender_domain","exact_inbox","exact_mailbox","shared_domain_requires_exact_inbox","shared_domain_not_verified","platform_domain","sender_domain_not_authorized","sending_domain","unaligned_apex_supported","author_identity_not_verified","author_domain_unaligned","author_domain","sender_domain_mismatch"]

- `outstanding` (optional)
  Type: object; nullable
  
  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.
  
  - `code` (required)
    Type: string
    
    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.
    
    enum: ["dns_records","provider_confirmation","domain_review","domain_permission"]
  
  - `action_required` (required)
    Type: boolean
    
    True when the customer has to act; false when the domain verifies on its own.
  
  - `items` (required)
    Type: array
    
    The DNS records or provider checks still outstanding, per domain.
    
    Items:
      Type: object
      
      - `domain` (required)
        Type: string
        
        The sending domain or its From domain.
      
      - `check` (required)
        Type: string
        
        A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).
  
  - `message` (required)
    Type: string
    
    Customer-facing explanation
  
  - `next_check_at` (required)
    Type: string, date-time; nullable
    
    When Nitrosend next checks this domain automatically; null when nothing is scheduled.

- `integration_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["pending","verified"]

- `dmarc_policy` (optional)
  Type: string
  
  Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
  
  enum: ["none","quarantine","reject"]

- `dmarc_recommended_policy` (optional)
  Type: string
  
  Nitrosend's recommended DMARC policy rung.
  
  enum: ["none","quarantine","reject"]

- `dmarc_observed_policy` (optional)
  Type: string; nullable
  
  Last live DMARC policy observed by Nitrosend.
  
  enum: ["none","quarantine","reject"]

- `dns_records` (optional)
  Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object; nullable

- `inbound_setup` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md); Type: object

- `dns_health` (optional)
  Type: object; nullable
  
  Additional properties: true

- `dns_setup_status` (optional)
  Type: string
  
  enum: ["unchecked","incomplete","ready","verified"]

- `verified_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/domains/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/domains/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/domains/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Remove a sending domain

`DELETE /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `unpair` (query, boolean, optional) - Confirm teardown of an identity pair after reviewing the paired-domain 422 response.
  Type: boolean
  
  default: false

Responses:

- 204: Domain deleted

- 422: Domain is paired or still has dependent inboxes

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `reason` (optional)
    Type: string
    
    enum: ["domain_paired","domain_in_use"]
  
  - `domain_id` (optional)
    Type: integer
  
  - `paired_with` (optional)
    Type: string
  
  - `counterpart_removed` (optional)
    Type: boolean

- 503: Upstream service unavailable

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/domains/0?unpair=false' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/domains/0?unpair=false', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/domains/0?unpair=false',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List shared subdomains and eligible destination brands

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `domain_id` (path, integer, required) - Verified apex or paired sending domain owned by the current brand.
  Type: integer

- `page` (query, integer, optional)
  Type: integer
  
  default: 1
  
  minimum: 1

- `q` (query, string, optional) - Filter the destination directory by brand or account name.
  Type: string
  
  maxLength: 120

Responses:

- 200: Subdomains (25 per page) and up to 100 eligible destinations.

Content type: application/json

Type: object

Schema: [SubdomainSharingSummary](https://docs.nitrosend.com/api/schemas/subdomainsharingsummary-18129033e5.md)

- `parent` (required)
  Type: object
  
  - `id` (optional)
    Type: integer
  
  - `name` (optional)
    Type: string

- `destinations` (required)
  Type: array
  
  maxItems: 100
  
  Items:
    Type: object
    
    - `account_id` (optional)
      Type: integer
    
    - `account_name` (optional)
      Type: string
    
    - `brand_id` (optional)
      Type: integer
    
    - `brand_sid` (optional)
      Type: string
    
    - `brand_name` (optional)
      Type: string

- `destinations_truncated` (required)
  Type: boolean

- `subdomains` (required)
  Type: array
  
  maxItems: 25
  
  Items:
    Reference: [SharedSubdomain](https://docs.nitrosend.com/api/schemas/sharedsubdomain-a7e22f14b2.md); Type: object

- `pagination` (required)
  Type: object
  
  - `page` (optional)
    Type: integer
  
  - `total_pages` (optional)
    Type: integer
  
  - `total_count` (optional)
    Type: integer

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/domains/0/subdomains?page=1' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/subdomains?page=1', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/domains/0/subdomains?page=1',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Share an exact subdomain with a brand or managed client

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `domain_id` (path, integer, required) - Verified apex or paired sending domain owned by the current brand.
  Type: integer

Request body: application/json (required)

Type: object

- `subdomain` (required)
  Type: object
  
  - `subdomain` (required)
    Type: string
    
    One DNS label below the apex.
    
    minLength: 1
    
    maxLength: 63
    
    pattern: "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"
  
  - `brand_sid` (required)
    Type: string
    
    Exact destination brand in this account or an eligible managed client.

Responses:

- 201: Shared child claim; use the destination brand's domain setup to configure DNS.

Content type: application/json

Type: object

Schema: [SharedSubdomain](https://docs.nitrosend.com/api/schemas/sharedsubdomain-a7e22f14b2.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  The recipient's visible From domain.

- `sending_domain_id` (required)
  Type: integer

- `sending_domain_name` (required)
  Type: string

- `account_id` (required)
  Type: integer

- `account_name` (required)
  Type: string

- `brand_id` (required)
  Type: integer

- `brand_sid` (required)
  Type: string

- `brand_name` (required)
  Type: string

- `active` (required)
  Type: boolean
  
  Domain permission is current; DNS verification remains a separate requirement.

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `dns_verified` (required)
  Type: boolean

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 429: Too many subdomain creation attempts. Retry later.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: Upstream service unavailable

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/domains/0/subdomains' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "subdomain": {
    "subdomain": "string",
    "brand_sid": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "subdomain": {
    "subdomain": "string",
    "brand_sid": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/subdomains', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "subdomain": {
    "subdomain": "string",
    "brand_sid": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/domains/0/subdomains',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Stop sharing a subdomain

`DELETE /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `domain_id` (path, integer, required)
  Type: integer

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Child claim with sharing stopped.

Content type: application/json

Type: object

Schema: [SharedSubdomain](https://docs.nitrosend.com/api/schemas/sharedsubdomain-a7e22f14b2.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  The recipient's visible From domain.

- `sending_domain_id` (required)
  Type: integer

- `sending_domain_name` (required)
  Type: string

- `account_id` (required)
  Type: integer

- `account_name` (required)
  Type: string

- `brand_id` (required)
  Type: integer

- `brand_sid` (required)
  Type: string

- `brand_name` (required)
  Type: string

- `active` (required)
  Type: boolean
  
  Domain permission is current; DNS verification remains a separate requirement.

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `dns_verified` (required)
  Type: boolean

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/domains/0/subdomains/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/subdomains/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/domains/0/subdomains/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Verify a domain

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: The domain, its DNS health and what is outstanding

Content type: application/json

Type: object

Schema: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `provider` (optional)
  Type: string
  
  default: "ses"

- `default_from_domain` (optional)
  Type: string
  
  Domain Nitrosend will use for visible From addresses when this sending domain is selected.

- `subdomain_sharing_available` (optional)
  Type: boolean
  
  The current principal can manage sharing on this verified apex.

- `shared_subdomain` (optional)
  Type: object
  
  Present only for a shared child, including after permission ends. DNS status is independent.
  
  - `active` (optional)
    Type: boolean
  
  - `parent_domain` (optional)
    Type: string; nullable
  
  - `message` (optional)
    Type: string; nullable

- `sender_authorization_reason` (optional)
  Type: string
  
  Machine-readable reason the default visible From domain is or is not authorized.
  
  enum: ["missing_sender_domain","exact_inbox","exact_mailbox","shared_domain_requires_exact_inbox","shared_domain_not_verified","platform_domain","sender_domain_not_authorized","sending_domain","unaligned_apex_supported","author_identity_not_verified","author_domain_unaligned","author_domain","sender_domain_mismatch"]

- `outstanding` (optional)
  Type: object; nullable
  
  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.
  
  - `code` (required)
    Type: string
    
    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.
    
    enum: ["dns_records","provider_confirmation","domain_review","domain_permission"]
  
  - `action_required` (required)
    Type: boolean
    
    True when the customer has to act; false when the domain verifies on its own.
  
  - `items` (required)
    Type: array
    
    The DNS records or provider checks still outstanding, per domain.
    
    Items:
      Type: object
      
      - `domain` (required)
        Type: string
        
        The sending domain or its From domain.
      
      - `check` (required)
        Type: string
        
        A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).
  
  - `message` (required)
    Type: string
    
    Customer-facing explanation
  
  - `next_check_at` (required)
    Type: string, date-time; nullable
    
    When Nitrosend next checks this domain automatically; null when nothing is scheduled.

- `integration_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["pending","verified"]

- `dmarc_policy` (optional)
  Type: string
  
  Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
  
  enum: ["none","quarantine","reject"]

- `dmarc_recommended_policy` (optional)
  Type: string
  
  Nitrosend's recommended DMARC policy rung.
  
  enum: ["none","quarantine","reject"]

- `dmarc_observed_policy` (optional)
  Type: string; nullable
  
  Last live DMARC policy observed by Nitrosend.
  
  enum: ["none","quarantine","reject"]

- `dns_records` (optional)
  Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object; nullable

- `inbound_setup` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md); Type: object

- `dns_health` (optional)
  Type: object; nullable
  
  Additional properties: true

- `dns_setup_status` (optional)
  Type: string
  
  enum: ["unchecked","incomplete","ready","verified"]

- `verified_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/domains/0/verify' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/domains/0/verify',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create an Entri bootstrap session for domain DNS setup

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json

Type: object

Schema: [EntriSessionRequest](https://docs.nitrosend.com/api/schemas/entrisessionrequest-3578743add.md)

- `apex_mx_override` (optional)
  Type: boolean
  
  Explicitly include the prepared company-inbox MX cutover in this session.
  
  default: false

- `apex_mx_confirmation` (optional)
  Type: string
  
  Exact apex domain name being approved. Required when apex_mx_override is true.

Responses:

- 200: Entri bootstrap payload

Content type: application/json

Type: object

Schema: [EntriSessionResponse](https://docs.nitrosend.com/api/schemas/entrisessionresponse-28835b7ca8.md)

- `domain` (required)
  Reference: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md); Type: object

- `entri` (required)
  Type: object
  
  - `application_id` (required)
    Type: string
  
  - `token` (required)
    Type: string
  
  - `prefilled_domain` (required)
    Type: string
  
  - `user_id` (required)
    Type: string
  
  - `dns_records` (required)
    Type: array
    
    Items:
      Reference: [EntriDnsRecord](https://docs.nitrosend.com/api/schemas/entridnsrecord-a42a1598c4.md); Type: object
  
  - `manual_dns_records` (required)
    Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Domain setup or apex mail cutover is not ready

Content type: application/json

Type: EntriSessionValidationError

Schema: [EntriSessionValidationError](https://docs.nitrosend.com/api/schemas/entrisessionvalidationerror-b75a934a6b.md)

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `blockers` (optional)
    Type: array
    
    Machine-readable reasons the apex MX cutover cannot proceed.
    
    Items:
      Type: string

- 429: Rate limit exceeded

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: Upstream service unavailable

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/domains/0/entri_session' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "apex_mx_override": false,
  "apex_mx_confirmation": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "apex_mx_override": false,
  "apex_mx_confirmation": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/entri_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "apex_mx_override": false,
  "apex_mx_confirmation": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/domains/0/entri_session',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Configure inbound delivery for a verified domain

`PUT /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

Schema: [DomainInboundSetupRequest](https://docs.nitrosend.com/api/schemas/domaininboundsetuprequest-41f610fba4.md)

- `inbound_setup` (required)
  Type: object
  
  - `method` (required)
    Type: string
    
    enum: ["provider_forwarding","mx"]
  
  - `provider` (optional)
    Type: string
    
    Required when method is provider_forwarding.
    
    enum: ["google_workspace","microsoft_365","zoho","other"]
  
  - `local_part` (optional)
    Type: string
    
    Select an exact existing address, or request creation subject to the current inbox allowance.
  
  - `inbox_id` (optional)
    Type: integer
    
    Existing inbox on this domain. Required for an ambiguous setup when local_part is omitted.
  
  - `display_name` (optional)
    Type: string; nullable
  
  - `prepare` (optional)
    Type: boolean
    
    Prepare apex receiving before opening the existing Entri MX connection. Does not change DNS.
    
    default: false
  
  - `no_existing_mail_service` (optional)
    Type: boolean
    
    Explicit first-mailbox choice. Rejected when public MX or a saved route identifies an existing mail service.
    
    default: false
  
  Additional properties: false

Additional properties: false

Responses:

- 200: Updated domain and inbound setup state

Content type: application/json

Type: object

Schema: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `provider` (optional)
  Type: string
  
  default: "ses"

- `default_from_domain` (optional)
  Type: string
  
  Domain Nitrosend will use for visible From addresses when this sending domain is selected.

- `subdomain_sharing_available` (optional)
  Type: boolean
  
  The current principal can manage sharing on this verified apex.

- `shared_subdomain` (optional)
  Type: object
  
  Present only for a shared child, including after permission ends. DNS status is independent.
  
  - `active` (optional)
    Type: boolean
  
  - `parent_domain` (optional)
    Type: string; nullable
  
  - `message` (optional)
    Type: string; nullable

- `sender_authorization_reason` (optional)
  Type: string
  
  Machine-readable reason the default visible From domain is or is not authorized.
  
  enum: ["missing_sender_domain","exact_inbox","exact_mailbox","shared_domain_requires_exact_inbox","shared_domain_not_verified","platform_domain","sender_domain_not_authorized","sending_domain","unaligned_apex_supported","author_identity_not_verified","author_domain_unaligned","author_domain","sender_domain_mismatch"]

- `outstanding` (optional)
  Type: object; nullable
  
  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.
  
  - `code` (required)
    Type: string
    
    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.
    
    enum: ["dns_records","provider_confirmation","domain_review","domain_permission"]
  
  - `action_required` (required)
    Type: boolean
    
    True when the customer has to act; false when the domain verifies on its own.
  
  - `items` (required)
    Type: array
    
    The DNS records or provider checks still outstanding, per domain.
    
    Items:
      Type: object
      
      - `domain` (required)
        Type: string
        
        The sending domain or its From domain.
      
      - `check` (required)
        Type: string
        
        A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).
  
  - `message` (required)
    Type: string
    
    Customer-facing explanation
  
  - `next_check_at` (required)
    Type: string, date-time; nullable
    
    When Nitrosend next checks this domain automatically; null when nothing is scheduled.

- `integration_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["pending","verified"]

- `dmarc_policy` (optional)
  Type: string
  
  Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
  
  enum: ["none","quarantine","reject"]

- `dmarc_recommended_policy` (optional)
  Type: string
  
  Nitrosend's recommended DMARC policy rung.
  
  enum: ["none","quarantine","reject"]

- `dmarc_observed_policy` (optional)
  Type: string; nullable
  
  Last live DMARC policy observed by Nitrosend.
  
  enum: ["none","quarantine","reject"]

- `dns_records` (optional)
  Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object; nullable

- `inbound_setup` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md); Type: object

- `dns_health` (optional)
  Type: object; nullable
  
  Additional properties: true

- `dns_setup_status` (optional)
  Type: string
  
  enum: ["unchecked","incomplete","ready","verified"]

- `verified_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PUT 'https://api.nitrosend.com/v1/my/domains/0/inbound_setup' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "inbound_setup": {
    "method": "provider_forwarding",
    "provider": "google_workspace",
    "local_part": "string",
    "inbox_id": 0,
    "display_name": "string",
    "prepare": false,
    "no_existing_mail_service": false
  }
}'
```

### JavaScript

```javascript
const body = `{
  "inbound_setup": {
    "method": "provider_forwarding",
    "provider": "google_workspace",
    "local_part": "string",
    "inbox_id": 0,
    "display_name": "string",
    "prepare": false,
    "no_existing_mail_service": false
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/inbound_setup', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "inbound_setup": {
    "method": "provider_forwarding",
    "provider": "google_workspace",
    "local_part": "string",
    "inbox_id": 0,
    "display_name": "string",
    "prepare": false,
    "no_existing_mail_service": false
  }
}'''

response = requests.put(
    'https://api.nitrosend.com/v1/my/domains/0/inbound_setup',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Verify provider forwarding for a domain inbox

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json

Type: object

- `inbox_id` (optional)
  Type: integer
  
  An inbox belonging to this domain and brand.

Additional properties: false

Responses:

- 200: Domain with refreshed forwarding probe state

Content type: application/json

Type: object

Schema: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `provider` (optional)
  Type: string
  
  default: "ses"

- `default_from_domain` (optional)
  Type: string
  
  Domain Nitrosend will use for visible From addresses when this sending domain is selected.

- `subdomain_sharing_available` (optional)
  Type: boolean
  
  The current principal can manage sharing on this verified apex.

- `shared_subdomain` (optional)
  Type: object
  
  Present only for a shared child, including after permission ends. DNS status is independent.
  
  - `active` (optional)
    Type: boolean
  
  - `parent_domain` (optional)
    Type: string; nullable
  
  - `message` (optional)
    Type: string; nullable

- `sender_authorization_reason` (optional)
  Type: string
  
  Machine-readable reason the default visible From domain is or is not authorized.
  
  enum: ["missing_sender_domain","exact_inbox","exact_mailbox","shared_domain_requires_exact_inbox","shared_domain_not_verified","platform_domain","sender_domain_not_authorized","sending_domain","unaligned_apex_supported","author_identity_not_verified","author_domain_unaligned","author_domain","sender_domain_mismatch"]

- `outstanding` (optional)
  Type: object; nullable
  
  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.
  
  - `code` (required)
    Type: string
    
    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.
    
    enum: ["dns_records","provider_confirmation","domain_review","domain_permission"]
  
  - `action_required` (required)
    Type: boolean
    
    True when the customer has to act; false when the domain verifies on its own.
  
  - `items` (required)
    Type: array
    
    The DNS records or provider checks still outstanding, per domain.
    
    Items:
      Type: object
      
      - `domain` (required)
        Type: string
        
        The sending domain or its From domain.
      
      - `check` (required)
        Type: string
        
        A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).
  
  - `message` (required)
    Type: string
    
    Customer-facing explanation
  
  - `next_check_at` (required)
    Type: string, date-time; nullable
    
    When Nitrosend next checks this domain automatically; null when nothing is scheduled.

- `integration_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["pending","verified"]

- `dmarc_policy` (optional)
  Type: string
  
  Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
  
  enum: ["none","quarantine","reject"]

- `dmarc_recommended_policy` (optional)
  Type: string
  
  Nitrosend's recommended DMARC policy rung.
  
  enum: ["none","quarantine","reject"]

- `dmarc_observed_policy` (optional)
  Type: string; nullable
  
  Last live DMARC policy observed by Nitrosend.
  
  enum: ["none","quarantine","reject"]

- `dns_records` (optional)
  Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object; nullable

- `inbound_setup` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md); Type: object

- `dns_health` (optional)
  Type: object; nullable
  
  Additional properties: true

- `dns_setup_status` (optional)
  Type: string
  
  enum: ["unchecked","incomplete","ready","verified"]

- `verified_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/domains/0/inbound_setup/probe' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "inbox_id": 0
}'
```

### JavaScript

```javascript
const body = `{
  "inbox_id": 0
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/domains/0/inbound_setup/probe', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "inbox_id": 0
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/domains/0/inbound_setup/probe',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List integrations (paginated)

`GET /v1/my/integrations`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `category` (query, string, optional)
  Type: string
  
  enum: ["email","sms","crm"]

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 30
  
  maximum: 100

Responses:

- 200: Paginated integrations

Content type: application/json

Type: array

Items:
  Reference: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md); Type: object

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/integrations?page=1&per=30' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations?page=1&per=30', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/integrations?page=1&per=30',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create or connect an email provider integration

`POST /v1/my/integrations`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [IntegrationWriteRequest](https://docs.nitrosend.com/api/schemas/integrationwriterequest-f190c0b2af.md)

- `integration` (required)
  Type: unknown
  
  oneOf:
    Reference: [MailgunIntegrationInput](https://docs.nitrosend.com/api/schemas/mailgunintegrationinput-85c7ec3a86.md); Type: object
  
    Reference: [SesIntegrationInput](https://docs.nitrosend.com/api/schemas/sesintegrationinput-985c0c6d4d.md); Type: object
  
    Reference: [PostmarkIntegrationInput](https://docs.nitrosend.com/api/schemas/postmarkintegrationinput-59f564e679.md); Type: object
  
    Reference: [ResendIntegrationInput](https://docs.nitrosend.com/api/schemas/resendintegrationinput-f4b80f4134.md); Type: object
  
    Reference: [SendgridIntegrationInput](https://docs.nitrosend.com/api/schemas/sendgridintegrationinput-f49ce9ac55.md); Type: object
  
    Reference: [ActiveCampaignIntegrationInput](https://docs.nitrosend.com/api/schemas/activecampaignintegrationinput-0412cfa28f.md); Type: object

Responses:

- 201: Integration created

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}'
```

### JavaScript

```javascript
const body = `{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get an integration

`GET /v1/my/integrations/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Integration

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/integrations/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/integrations/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Disconnect an integration

`DELETE /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `confirm` (query, boolean, required) - Must be true to confirm the destructive action.
  Type: boolean

Responses:

- 204: Integration disconnected

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The selected sender still has active or unsettled work.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/integrations/0?confirm=true' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0?confirm=true', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/integrations/0?confirm=true',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update an email provider integration

`PATCH /v1/my/integrations/{id}`

Updates credentials or operational fields for an existing email provider.
The provider cannot be changed once the integration exists.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

Schema: [IntegrationWriteRequest](https://docs.nitrosend.com/api/schemas/integrationwriterequest-f190c0b2af.md)

- `integration` (required)
  Type: unknown
  
  oneOf:
    Reference: [MailgunIntegrationInput](https://docs.nitrosend.com/api/schemas/mailgunintegrationinput-85c7ec3a86.md); Type: object
  
    Reference: [SesIntegrationInput](https://docs.nitrosend.com/api/schemas/sesintegrationinput-985c0c6d4d.md); Type: object
  
    Reference: [PostmarkIntegrationInput](https://docs.nitrosend.com/api/schemas/postmarkintegrationinput-59f564e679.md); Type: object
  
    Reference: [ResendIntegrationInput](https://docs.nitrosend.com/api/schemas/resendintegrationinput-f4b80f4134.md); Type: object
  
    Reference: [SendgridIntegrationInput](https://docs.nitrosend.com/api/schemas/sendgridintegrationinput-f49ce9ac55.md); Type: object
  
    Reference: [ActiveCampaignIntegrationInput](https://docs.nitrosend.com/api/schemas/activecampaignintegrationinput-0412cfa28f.md); Type: object

Responses:

- 200: Integration updated

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/integrations/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}'
```

### JavaScript

```javascript
const body = `{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/integrations/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Test integration connectivity

`POST /v1/my/integrations/{id}/test`

A passing first test of a contact-sync integration that has never
synced (ActiveCampaign) also starts its first sync.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Tested integration

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: The provider refused the connection, for example "ActiveCampaign rejected the API key".

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/0/test' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/0/test',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Set an integration as the primary provider for its category

`PATCH /v1/my/integrations/{id}/primary`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Integration marked primary

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/integrations/0/primary' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/primary', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.patch(
    'https://api.nitrosend.com/v1/my/integrations/0/primary',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get an integration's versioned profile sync contract

`GET /v1/my/integrations/{integration_id}/sync_configuration`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `integration_id` (path, integer, required)
  Type: integer

Responses:

- 200: Safe sync configuration

Content type: application/json

Type: object

Schema: [IntegrationSyncConfiguration](https://docs.nitrosend.com/api/schemas/integrationsyncconfiguration-46ed32cba5.md)

- `integration_id` (required)
  Type: integer

- `provider` (required)
  Type: string

- `sync_contract` (required)
  Reference: [IntegrationSyncContract](https://docs.nitrosend.com/api/schemas/integrationsynccontract-13e9430fbb.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/integrations/0/sync_configuration' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/sync_configuration', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/integrations/0/sync_configuration',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Validate and update an integration's profile sync contract

`PATCH /v1/my/integrations/{integration_id}/sync_configuration`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `integration_id` (path, integer, required)
  Type: integer

- `confirm_deselection` (query, boolean, optional)
  Type: boolean
  
  default: false

Request body: application/json (required)

Type: object

Schema: [IntegrationSyncConfigurationWriteRequest](https://docs.nitrosend.com/api/schemas/integrationsyncconfigurationwriterequest-34d5a37068.md)

- `sync_contract` (required)
  Reference: [IntegrationSyncContract](https://docs.nitrosend.com/api/schemas/integrationsynccontract-13e9430fbb.md); Type: object

Responses:

- 200: Updated safe sync configuration

Content type: application/json

Type: object

Schema: [IntegrationSyncConfiguration](https://docs.nitrosend.com/api/schemas/integrationsyncconfiguration-46ed32cba5.md)

- `integration_id` (required)
  Type: integer

- `provider` (required)
  Type: string

- `sync_contract` (required)
  Reference: [IntegrationSyncContract](https://docs.nitrosend.com/api/schemas/integrationsynccontract-13e9430fbb.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/integrations/0/sync_configuration?confirm_deselection=false' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "sync_contract": {
    "version": 1,
    "mirror_lists": true,
    "updated_at": "2024-01-15T09:30:00Z",
    "objects": [
      {
        "object_id": "string",
        "object_slug": "string",
        "label": "string",
        "mode": "addressable",
        "enabled": true,
        "field_policy": "all_supported",
        "selected_fields": [
          "string"
        ],
        "excluded_fields": [
          "string"
        ],
        "relationship": {
          "attribute_slug": "string",
          "target_object_slug": "people"
        },
        "trait_mapping": {
          "kind": "deal_pipeline",
          "stage_attribute": "string",
          "closed_stage_values": [
            "string"
          ],
          "amount_attribute": "string",
          "currency_attribute": "string"
        },
        "managed_audience_mapping_key": "string",
        "mirror_lists": true
      }
    ]
  }
}'
```

### JavaScript

```javascript
const body = `{
  "sync_contract": {
    "version": 1,
    "mirror_lists": true,
    "updated_at": "2024-01-15T09:30:00Z",
    "objects": [
      {
        "object_id": "string",
        "object_slug": "string",
        "label": "string",
        "mode": "addressable",
        "enabled": true,
        "field_policy": "all_supported",
        "selected_fields": [
          "string"
        ],
        "excluded_fields": [
          "string"
        ],
        "relationship": {
          "attribute_slug": "string",
          "target_object_slug": "people"
        },
        "trait_mapping": {
          "kind": "deal_pipeline",
          "stage_attribute": "string",
          "closed_stage_values": [
            "string"
          ],
          "amount_attribute": "string",
          "currency_attribute": "string"
        },
        "managed_audience_mapping_key": "string",
        "mirror_lists": true
      }
    ]
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/sync_configuration?confirm_deselection=false', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "sync_contract": {
    "version": 1,
    "mirror_lists": true,
    "updated_at": "2024-01-15T09:30:00Z",
    "objects": [
      {
        "object_id": "string",
        "object_slug": "string",
        "label": "string",
        "mode": "addressable",
        "enabled": true,
        "field_policy": "all_supported",
        "selected_fields": [
          "string"
        ],
        "excluded_fields": [
          "string"
        ],
        "relationship": {
          "attribute_slug": "string",
          "target_object_slug": "people"
        },
        "trait_mapping": {
          "kind": "deal_pipeline",
          "stage_attribute": "string",
          "closed_stage_values": [
            "string"
          ],
          "amount_attribute": "string",
          "currency_attribute": "string"
        },
        "managed_audience_mapping_key": "string",
        "mirror_lists": true
      }
    ]
  }
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/integrations/0/sync_configuration?confirm_deselection=false',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Discover safe provider objects and attributes for profile sync

`GET /v1/my/integrations/{integration_id}/sync_configuration/discovery`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `integration_id` (path, integer, required)
  Type: integer

Responses:

- 200: Sync configuration and bounded provider discovery metadata

Content type: application/json

Type: unknown

allOf:
  Reference: [IntegrationSyncConfiguration](https://docs.nitrosend.com/api/schemas/integrationsyncconfiguration-46ed32cba5.md); Type: object

  Type: object
  
  - `discovery` (required)
    Reference: [IntegrationSyncDiscovery](https://docs.nitrosend.com/api/schemas/integrationsyncdiscovery-04ac2fff94.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/integrations/0/sync_configuration/discovery' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/sync_configuration/discovery', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/integrations/0/sync_configuration/discovery',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Start Attio OAuth connect flow

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: OAuth authorize URL

Content type: application/json

Type: object

- `authorize_url` (required)
  Type: string, uri

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/attio/connect' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/attio/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/attio/connect',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Start HubSpot OAuth connect flow

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: OAuth authorize URL

Content type: application/json

Type: object

- `authorize_url` (required)
  Type: string, uri

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/hubspot/connect' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/hubspot/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/hubspot/connect',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Connect a Gmail, Google Workspace or Microsoft 365 sending mailbox

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `provider` (path, string, required)
  Type: string
  
  enum: ["gmail","microsoft365"]

Request body: application/json

Type: object

- `sending_domain_id` (optional)
  Type: integer
  
  Optional existing brand domain to bind explicitly. A new connection without it is exact-address only.

- `return_to` (optional)
  Type: string
  
  Signed allowlisted app-relative return path. External origins and traversal are rejected.
  
  maxLength: 2048

- `integration_id` (optional)
  Type: integer
  
  Existing connection to reconnect without changing its mailbox.

Additional properties: false

Responses:

- 200: Provider authorization URL

Content type: application/json

Type: object

- `authorize_url` (required)
  Type: string, uri

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/gmail/connect' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "sending_domain_id": 0,
  "return_to": "string",
  "integration_id": 0
}'
```

### JavaScript

```javascript
const body = `{
  "sending_domain_id": 0,
  "return_to": "string",
  "integration_id": 0
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/gmail/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "sending_domain_id": 0,
  "return_to": "string",
  "integration_id": 0
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/gmail/connect',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Test SMTP and IMAP credentials and send an address verification code

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `integration_id` (optional)
  Type: integer
  
  Existing pending SMTP connection.

- `mailbox` (required)
  Type: object
  
  - `mailbox_address` (required)
    Type: string, email
  
  - `smtp_host` (required)
    Type: string
  
  - `smtp_port` (required)
    Type: integer
    
    enum: [465,587,2525]
  
  - `smtp_username` (required)
    Type: string
  
  - `smtp_password` (required)
    Type: string, password
    
    writeOnly: true
  
  - `imap_host` (required)
    Type: string
  
  - `imap_port` (required)
    Type: integer
    
    enum: [993]
  
  - `imap_username` (required)
    Type: string
  
  - `imap_password` (optional)
    Type: string, password
    
    Defaults to SMTP password.
    
    writeOnly: true
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string

Responses:

- 200: Pending mailbox connection; code sent to its address.

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/smtp/connect' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "integration_id": 0,
  "mailbox": {
    "mailbox_address": "user@example.com",
    "smtp_host": "string",
    "smtp_port": 465,
    "smtp_username": "string",
    "smtp_password": "********",
    "imap_host": "string",
    "imap_port": 993,
    "imap_username": "string",
    "imap_password": "********",
    "sent_folder": "string",
    "junk_folder": "string"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "integration_id": 0,
  "mailbox": {
    "mailbox_address": "user@example.com",
    "smtp_host": "string",
    "smtp_port": 465,
    "smtp_username": "string",
    "smtp_password": "********",
    "imap_host": "string",
    "imap_port": 993,
    "imap_username": "string",
    "imap_password": "********",
    "sent_folder": "string",
    "junk_folder": "string"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/smtp/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "integration_id": 0,
  "mailbox": {
    "mailbox_address": "user@example.com",
    "smtp_host": "string",
    "smtp_port": 465,
    "smtp_username": "string",
    "smtp_password": "********",
    "imap_host": "string",
    "imap_port": 993,
    "imap_username": "string",
    "imap_password": "********",
    "sent_folder": "string",
    "junk_folder": "string"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/smtp/connect',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Activate a pending SMTP mailbox using its address verification code

`POST /v1/my/integrations/{id}/verify_mailbox`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `code` (required)
  Type: string

Responses:

- 200: Connected exact-address mailbox.

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/0/verify_mailbox' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "code": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "code": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/verify_mailbox', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "code": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/0/verify_mailbox',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Read this SMTP connection's feedback endpoint, signing secret, and recent receipts

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: SMTP feedback setup and the 20 most recent receipts.

Content type: application/json

Type: object

Schema: [SmtpFeedbackSetup](https://docs.nitrosend.com/api/schemas/smtpfeedbacksetup-d5fbfaab57.md)

- `url` (required)
  Type: string, uri

- `signing_secret` (required)
  Type: string
  
  Connection-specific whsec_ key; never included in integration lists or broadcasts.

- `signing_format` (required)
  Type: string
  
  enum: ["standard_webhooks"]

- `events` (required)
  Type: array
  
  maxItems: 20
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: string
    
    - `type` (optional)
      Type: string
      
      enum: ["test","delivered","bounced","complained"]
    
    - `status` (optional)
      Type: string
      
      enum: ["pending","processing","processed","ignored","failed"]
    
    - `received_at` (optional)
      Type: string, date-time
    
    - `processed_at` (optional)
      Type: string, date-time; nullable
    
    - `message_id` (optional)
      Type: string; nullable
    
    - `recipient` (optional)
      Type: string; nullable
    
    - `error_message` (optional)
      Type: string; nullable

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/integrations/0/smtp_feedback' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/smtp_feedback', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/integrations/0/smtp_feedback',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Replace this SMTP connection's feedback signing secret

`POST /v1/my/integrations/{id}/smtp_feedback/rotate`

The old secret is invalid immediately. Previously authenticated receipts still process.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Setup with the replacement secret.

Content type: application/json

Type: object

Schema: [SmtpFeedbackSetup](https://docs.nitrosend.com/api/schemas/smtpfeedbacksetup-d5fbfaab57.md)

- `url` (required)
  Type: string, uri

- `signing_secret` (required)
  Type: string
  
  Connection-specific whsec_ key; never included in integration lists or broadcasts.

- `signing_format` (required)
  Type: string
  
  enum: ["standard_webhooks"]

- `events` (required)
  Type: array
  
  maxItems: 20
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: string
    
    - `type` (optional)
      Type: string
      
      enum: ["test","delivered","bounced","complained"]
    
    - `status` (optional)
      Type: string
      
      enum: ["pending","processing","processed","ignored","failed"]
    
    - `received_at` (optional)
      Type: string, date-time
    
    - `processed_at` (optional)
      Type: string, date-time; nullable
    
    - `message_id` (optional)
      Type: string; nullable
    
    - `recipient` (optional)
      Type: string; nullable
    
    - `error_message` (optional)
      Type: string; nullable

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/0/smtp_feedback/rotate' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/0/smtp_feedback/rotate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/0/smtp_feedback/rotate',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Receive signed delivery feedback for one SMTP connection

`POST /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,<base64 digest>'.
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.


Authentication: no security requirement declared for this operation.

Parameters:

- `id` (path, integer, required)
  Type: integer

- `webhook-id` (header, string, required) - Unique event ID, stable across retries.
  Type: string
  
  maxLength: 128
  
  pattern: "^[A-Za-z0-9_.-]+$"

- `webhook-timestamp` (header, string, required) - Unix seconds at the time this attempt is signed.
  Type: string
  
  pattern: "^\\d{1,12}$"

- `webhook-signature` (header, string, required)
  Type: string
  
  maxLength: 1024

Request body: application/json (required)

Type: SmtpFeedbackPayload

Schema: [SmtpFeedbackPayload](https://docs.nitrosend.com/api/schemas/smtpfeedbackpayload-db5f52d237.md)

oneOf:
  Type: object
  
  - `type` (required)
    Type: string
    
    enum: ["test"]
  
  Additional properties: false

  Type: object
  
  - `type` (required)
    Type: string
    
    enum: ["delivered","bounced","complained"]
  
  - `message_id` (required)
    Type: string
    
    Original RFC Message-ID, with or without surrounding angle brackets.
    
    maxLength: 255
  
  - `recipient` (required)
    Type: string, email
    
    maxLength: 254
  
  - `occurred_at` (required)
    Type: string, date-time
    
    Outcome time, no more than five minutes in the future.
  
  - `status` (optional)
    Type: string
    
    Required only for bounced events. Recipient failures suppress; policy failures remain delivery_failed observations.
    
    pattern: "^[45]\\.\\d{1,3}\\.\\d{1,3}$"
  
  - `nitrosend_message_id` (optional)
    Type: integer, int64
    
    Optional original X-Nitro-Message-Id, supplied together with dispatch_token to correlate an outcome before the send result is persisted.
    
    minimum: 1
    
    maximum: 9223372036854776000
  
  - `dispatch_token` (optional)
    Type: string
    
    Original X-Nitro-Dispatch header, supplied together with nitrosend_message_id.
    
    maxLength: 2048
  
  allOf:
    Type: unknown
  
  Additional properties: false

Responses:

- 200: Durable receipt accepted, including identical retries.

- 400: Invalid JSON, fields, timestamp, event type, or event data.

- 403: Unknown connection or invalid, missing, or stale signing credentials.

- 409: Event ID was previously used for different content.

- 413: Body exceeds 16 KiB.

- 429: Callback rate exceeded; retry with backoff.

- 500: Receipt or enqueue failed; retry the same event ID.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/hooks/smtp/0/events' \
  -H 'webhook-id: string' \
  -H 'webhook-timestamp: string' \
  -H 'webhook-signature: string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "type": "test"
}'
```

### JavaScript

```javascript
const body = `{
  "type": "test"
}`;

const response = await fetch('https://api.nitrosend.com/hooks/smtp/0/events', {
  method: 'POST',
  headers: {
    'webhook-id': 'string',
    'webhook-timestamp': 'string',
    'webhook-signature': 'string',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "type": "test"
}'''

response = requests.post(
    'https://api.nitrosend.com/hooks/smtp/0/events',
    data=body.encode('utf-8'),
    headers={
        'webhook-id': 'string',
        'webhook-timestamp': 'string',
        'webhook-signature': 'string',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Complete a sending mailbox connection

`GET /integrations/{provider}/callback`

Authentication: no security requirement declared for this operation.

Parameters:

- `provider` (path, string, required)
  Type: string
  
  enum: ["gmail","microsoft365"]

- `state` (query, string, required)
  Type: string

- `code` (query, string, required)
  Type: string

Responses:

- 303: 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.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/gmail/callback?state=string&code=string'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/gmail/callback?state=string&code=string', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/integrations/gmail/callback?state=string&code=string')
print(response.text)
```


## Start Shopify OAuth connect flow

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `shopify` (required)
  Type: object
  
  - `shop` (required)
    Type: string
    
    Example:
    
    ```json
    "test-shop.myshopify.com"
    ```
  
  - `app_key` (optional)
    Type: string
    
    Explicit registered app identity; omitted requests resolve the existing shop registration.
    
    Example:
    
    ```json
    "appstore"
    ```

Responses:

- 200: OAuth authorize URL

Content type: application/json

Type: object

- `authorize_url` (required)
  Type: string, uri

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/shopify/connect' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "shopify": {
    "shop": "test-shop.myshopify.com",
    "app_key": "appstore"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "shopify": {
    "shop": "test-shop.myshopify.com",
    "app_key": "appstore"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/shopify/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "shopify": {
    "shop": "test-shop.myshopify.com",
    "app_key": "appstore"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/shopify/connect',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Connect a merchant-owned Shopify app

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [ShopifyMerchantCredentialRequest](https://docs.nitrosend.com/api/schemas/shopifymerchantcredentialrequest-68919b351e.md)

- `shopify` (required)
  Type: object
  
  - `shop` (required)
    Type: string
    
    Permanent myshopify.com domain or shop slug.
  
  - `client_id` (required)
    Type: string
    
    Client ID for the merchant-owned Shopify app.
    
    writeOnly: true
  
  - `client_secret` (required)
    Type: string, password
    
    Client secret for the merchant-owned Shopify app.
    
    writeOnly: true
  
  Additional properties: false

Responses:

- 200: Existing merchant-managed Shopify connection replaced

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 201: Merchant-managed Shopify connection created

Content type: application/json

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Missing fields, invalid credentials, missing scopes, or a shop ownership conflict

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `missing_scopes` (optional)
    Type: array
    
    Items:
      Type: string
      
      enum: ["read_customers","read_orders","read_products"]
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/shopify/credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "shopify": {
    "shop": "string",
    "client_id": "string",
    "client_secret": "********"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "shopify": {
    "shop": "string",
    "client_id": "string",
    "client_secret": "********"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/shopify/credentials', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "shopify": {
    "shop": "string",
    "client_id": "string",
    "client_secret": "********"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/shopify/credentials',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Start Stripe App OAuth connect flow

`POST /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json

Type: object

- `stripe` (optional)
  Type: object
  
  - `mode` (optional)
    Type: string
    
    default: "live"
    
    enum: ["live","test"]

Responses:

- 200: OAuth authorize URL

Content type: application/json

Type: object

- `authorize_url` (required)
  Type: string, uri

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/stripe/connect' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "stripe": {
    "mode": "live"
  }
}'
```

### JavaScript

```javascript
const body = `{
  "stripe": {
    "mode": "live"
  }
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/integrations/stripe/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "stripe": {
    "mode": "live"
  }
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/integrations/stripe/connect',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Public Stripe App install entry

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `mode` (query, string, optional)
  Type: string
  
  default: "live"
  
  enum: ["live","test"]

Responses:

- 302: Redirect to the Stripe App install link

- 404: The Stripe App is not configured

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/stripe/install?mode=live' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/stripe/install?mode=live', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/integrations/stripe/install?mode=live',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Stripe App OAuth callback endpoint

`GET /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).


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `code` (query, string, optional)
  Type: string

- `state` (query, string, optional)
  Type: string

- `error` (query, string, optional)
  Type: string

- `error_description` (query, string, optional)
  Type: string

Responses:

- 302: Public install redirect into the app or to sign in.

- 303: Redirect to the app connection-result page with safe result codes and authorized context.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/stripe/callback' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/stripe/callback', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/integrations/stripe/callback',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Attio OAuth callback endpoint

`GET /integrations/attio/callback`

Public callback endpoint used by Attio after user authorization.
Verifies signed state, exchanges auth code, and finalizes Attio integration connection.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `code` (query, string, optional)
  Type: string

- `state` (query, string, optional)
  Type: string

- `error` (query, string, optional)
  Type: string

- `error_description` (query, string, optional)
  Type: string

Responses:

- 303: Redirect to the app connection-result page with safe result codes and authorized context.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/attio/callback' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/attio/callback', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/integrations/attio/callback',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## HubSpot OAuth callback endpoint

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `code` (query, string, optional)
  Type: string

- `state` (query, string, optional)
  Type: string

- `error` (query, string, optional)
  Type: string

- `error_description` (query, string, optional)
  Type: string

Responses:

- 303: Redirect to the app connection-result page with safe result codes and authorized context.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/hubspot/callback' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/hubspot/callback', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/integrations/hubspot/callback',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Shopify OAuth callback endpoint

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `code` (query, string, optional)
  Type: string

- `state` (query, string, optional)
  Type: string

- `shop` (query, string, optional)
  Type: string

- `hmac` (query, string, optional)
  Type: string

- `timestamp` (query, string, optional)
  Type: string

- `error` (query, string, optional)
  Type: string

- `error_description` (query, string, optional)
  Type: string

Responses:

- 302: Connected; public apps return to Shopify Admin, custom apps return to the Nitrosend integration

- 400: Invalid callback request

Content type: text/html

Type: string

- 422: OAuth exchange failure

Content type: text/html

Type: string

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/shopify/callback' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/shopify/callback', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/integrations/shopify/callback',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Receive a Stripe App event for a connected account

`POST /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.


Authentication: no security requirement declared for this operation.

Parameters:

- `Stripe-Signature` (header, string, required)
  Type: string

Request body: application/json (required)

Type: object

Additional properties: true

Responses:

- 200: Verified event acknowledged

- 403: Invalid signature or unconfigured secret

- 500: Verified event could not be enqueued

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/hooks/stripe_apps' \
  -H 'Stripe-Signature: string' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/hooks/stripe_apps', {
  method: 'POST',
  headers: {
    'Stripe-Signature': 'string',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/hooks/stripe_apps',
    data='{}'.encode('utf-8'),
    headers={
        'Stripe-Signature': 'string',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Receive an App Store Shopify webhook

`POST /hooks/shopify/events`

Uses the App Store app credentials when no app key is present.

Authentication: no security requirement declared for this operation.

Parameters:

- `X-Shopify-Hmac-Sha256` (header, string, required)
  Type: string

- `X-Shopify-Shop-Domain` (header, string, required)
  Type: string

- `X-Shopify-Topic` (header, string, required)
  Type: string

Request body: application/json (required)

Type: object

Additional properties: true

Responses:

- 200: Verified webhook acknowledged

- 400: Invalid JSON payload

- 401: Invalid App Store HMAC

- 500: Verified webhook could not be applied

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/hooks/shopify/events' \
  -H 'X-Shopify-Hmac-Sha256: string' \
  -H 'X-Shopify-Shop-Domain: string' \
  -H 'X-Shopify-Topic: string' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/hooks/shopify/events', {
  method: 'POST',
  headers: {
    'X-Shopify-Hmac-Sha256': 'string',
    'X-Shopify-Shop-Domain': 'string',
    'X-Shopify-Topic': 'string',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/hooks/shopify/events',
    data='{}'.encode('utf-8'),
    headers={
        'X-Shopify-Hmac-Sha256': 'string',
        'X-Shopify-Shop-Domain': 'string',
        'X-Shopify-Topic': 'string',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Receive a merchant-managed Shopify webhook

`POST /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.


Authentication: no security requirement declared for this operation.

Parameters:

- `X-Shopify-Hmac-Sha256` (header, string, required)
  Type: string

- `X-Shopify-Shop-Domain` (header, string, required)
  Type: string

- `X-Shopify-Topic` (header, string, required)
  Type: string

- `X-Shopify-Webhook-Id` (header, string, optional)
  Type: string

Request body: application/json (required)

Type: object

Additional properties: true

Responses:

- 200: Verified supported webhook processed or unsupported topic safely acknowledged

- 400: Verified supported webhook contained invalid JSON

- 401: Webhook could not be authenticated

- 500: Verified webhook could not be applied

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/hooks/shopify/merchant/events' \
  -H 'X-Shopify-Hmac-Sha256: string' \
  -H 'X-Shopify-Shop-Domain: string' \
  -H 'X-Shopify-Topic: string' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/hooks/shopify/merchant/events', {
  method: 'POST',
  headers: {
    'X-Shopify-Hmac-Sha256': 'string',
    'X-Shopify-Shop-Domain': 'string',
    'X-Shopify-Topic': 'string',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/hooks/shopify/merchant/events',
    data='{}'.encode('utf-8'),
    headers={
        'X-Shopify-Hmac-Sha256': 'string',
        'X-Shopify-Shop-Domain': 'string',
        'X-Shopify-Topic': 'string',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Receive a Shopify webhook for a named app

`POST /hooks/shopify/events/{app_key}`

Authentication: no security requirement declared for this operation.

Parameters:

- `app_key` (path, string, required)
  Type: string
  
  enum: ["custom"]

- `X-Shopify-Hmac-Sha256` (header, string, required)
  Type: string

- `X-Shopify-Shop-Domain` (header, string, required)
  Type: string

- `X-Shopify-Topic` (header, string, required)
  Type: string

Request body: application/json (required)

Type: object

Additional properties: true

Responses:

- 200: Verified webhook acknowledged

- 400: Invalid JSON payload

- 401: Invalid app-specific HMAC

- 500: Verified webhook could not be applied

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/hooks/shopify/events/custom' \
  -H 'X-Shopify-Hmac-Sha256: string' \
  -H 'X-Shopify-Shop-Domain: string' \
  -H 'X-Shopify-Topic: string' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/hooks/shopify/events/custom', {
  method: 'POST',
  headers: {
    'X-Shopify-Hmac-Sha256': 'string',
    'X-Shopify-Shop-Domain': 'string',
    'X-Shopify-Topic': 'string',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/hooks/shopify/events/custom',
    data='{}'.encode('utf-8'),
    headers={
        'X-Shopify-Hmac-Sha256': 'string',
        'X-Shopify-Shop-Domain': 'string',
        'X-Shopify-Topic': 'string',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Open or resume the embedded Shopify app

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Responses:

- 200: Embedded Shopify integration opened

Content type: application/json

Type: object

- `integration_id` (required)
  Type: integer

- `manage_url` (optional)
  Type: string, uri; nullable

- `requires_plan` (required)
  Type: boolean

- `redirect_to` (required)
  Type: string

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Embedded install needs recovery or cannot be opened

Content type: application/json

Type: object

- `error` (required)
  Type: string

- `message` (required)
  Type: string

- `connect_path` (optional)
  Type: string
  
  Relative dashboard path, only present for existing_account recovery

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/integrations/shopify/session' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/shopify/session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/integrations/shopify/session',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Reconcile Shopify App Pricing after plan management

`GET /integrations/shopify/billing/callback`

Authentication: no security requirement declared for this operation.

Parameters:

- `shop` (query, string, required)
  Type: string
  
  Example:
  
  ```json
  "test-shop.myshopify.com"
  ```

Responses:

- 302: Redirect back to the app in Shopify Admin

- 400: Invalid Shopify shop domain

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/integrations/shopify/billing/callback?shop=test-shop.myshopify.com'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/integrations/shopify/billing/callback?shop=test-shop.myshopify.com', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/integrations/shopify/billing/callback?shop=test-shop.myshopify.com')
print(response.text)
```


## Ingest a Shopify Web Pixel event

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "bearerAuth": []
  }
]
```

- bearerAuth

Request body: application/json (required)

Type: object

- `event_id` (required)
  Type: string

- `event_name` (required)
  Type: string
  
  enum: ["product_viewed","product_added_to_cart","product_removed_from_cart"]

- `customer_id` (optional)
  Type: string

- `email` (optional)
  Type: string, email

- `phone` (optional)
  Type: string

- `properties` (optional)
  Type: object
  
  Additional properties: true

Responses:

- 202: Event accepted, ignored, or dropped

Content type: application/json

Type: object

- `ok` (required)
  Type: boolean

- `outcome` (required)
  Type: string
  
  enum: ["captured","ignored","dropped"]

- `event_id` (optional)
  Type: integer

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/public/shopify/events' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "event_id": "string",
  "event_name": "product_viewed",
  "customer_id": "string",
  "email": "user@example.com",
  "phone": "string",
  "properties": {}
}'
```

### JavaScript

```javascript
const body = `{
  "event_id": "string",
  "event_name": "product_viewed",
  "customer_id": "string",
  "email": "user@example.com",
  "phone": "string",
  "properties": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/public/shopify/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "event_id": "string",
  "event_name": "product_viewed",
  "customer_id": "string",
  "email": "user@example.com",
  "phone": "string",
  "properties": {}
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/public/shopify/events',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List brands (paginated)

`GET /v1/my/brands`

Brand-scoped credentials see only their own brand. Signed-in account users see their accessible account's brands.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `per` (query, integer, optional)
  Type: integer
  
  default: 100
  
  maximum: 100

Responses:

- 200: All brands for the account

Content type: application/json

Type: array

Items:
  Reference: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands?page=1&per=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands?page=1&per=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands?page=1&per=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create a brand

`POST /v1/my/brands`

Requires a signed-in account user. Brand-scoped credentials cannot create brands.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string
  
  Internal brand name; mirrors company_name when company_name is omitted

- `brand_color` (optional)
  Type: string
  
  pattern: "^#[0-9a-fA-F]{6}$"

- `text_color` (optional)
  Type: string
  
  pattern: "^#[0-9a-fA-F]{6}$"

- `bg_color` (optional)
  Type: string
  
  pattern: "^#[0-9a-fA-F]{6}$"

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string

- `font_body` (optional)
  Type: string

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string

- `physical_address` (optional)
  Type: string

- `company_name` (optional)
  Type: string

- `logo` (optional)
  Type: string
  
  Signed blob ID or URL

- `email_from_name` (optional)
  Type: string

- `email_from_email` (optional)
  Type: string, email

- `email_reply_to` (optional)
  Type: string, email

- `email_view_online` (optional)
  Type: boolean

- `email_view_online_placement` (optional)
  Type: string
  
  Where the View in browser link goes: at the top of the email, or beside the footer's Unsubscribe link.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  Inject the open-tracking pixel into this brand's emails.

- `email_track_clicks` (optional)
  Type: boolean
  
  Rewrite this brand's links for click tracking.

- `test_email_recipients` (optional)
  Type: array
  
  maxItems: 5
  
  Items:
    Type: string, email

- `links` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string, uri
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `default_header` (optional)
  Type: object
  
  Additional properties: true

- `default_footer` (optional)
  Type: object
  
  Additional properties: true

- `default_theme` (optional)
  Type: object
  
  Additional properties: true

Responses:

- 201: Brand created

Content type: application/json

Type: object

Schema: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md)

- `id` (optional)
  Type: integer

- `sid` (optional)
  Type: string
  
  Public secure identifier (non-sequential)
  
  readOnly: true

- `account_id` (optional)
  Type: integer

- `brand_color` (optional)
  Type: string; nullable

- `text_color` (optional)
  Type: string; nullable

- `bg_color` (optional)
  Type: string; nullable

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string; nullable

- `font_body` (optional)
  Type: string; nullable

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string; nullable

- `default_header` (optional)
  Type: object; nullable

- `default_footer` (optional)
  Type: object; nullable

- `default_theme` (optional)
  Type: object; nullable

- `physical_address` (optional)
  Type: string; nullable

- `company_name` (optional)
  Type: string; nullable

- `source_url` (optional)
  Type: string; nullable

- `last_scraped_at` (optional)
  Type: string, date-time; nullable

- `links` (optional)
  Type: array; nullable
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `logo` (optional)
  Type: string; nullable
  
  Logo URL

- `complete` (optional)
  Type: boolean
  
  True when brand_color and company_name are set

- `email_from_name` (optional)
  Type: string; nullable

- `email_from_email` (optional)
  Type: string; nullable

- `email_reply_to` (optional)
  Type: string; nullable

- `from_email_domain_status` (optional)
  Type: string
  
  Authorization state of the configured visible From address.
  
  enum: ["blank","verified","unverified"]

- `effective_from_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_reply_to` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_sending_domain` (optional)
  Type: string; nullable
  
  readOnly: true

- `effective_source_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `sender_configured` (optional)
  Type: boolean
  
  readOnly: true

- `email_view_online` (optional)
  Type: boolean
  
  Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

- `email_view_online_placement` (optional)
  Type: string
  
  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.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  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_clicks` (optional)
  Type: boolean
  
  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_recipients` (optional)
  Type: array
  
  Items:
    Type: string, email

- `onboarding_state` (optional)
  Type: object
  
  JSONB — keys are step names, values are completion metadata
  
  Additional properties: true

- `onboarding` (optional)
  Type: object
  
  - `steps` (optional)
    Type: object
    
    Current state of each onboarding step
  
  - `progress` (optional)
    Type: object
    
    - `completed` (optional)
      Type: integer
    
    - `total` (optional)
      Type: integer

- `domain_verified` (optional)
  Type: boolean

- `can_send` (optional)
  Type: boolean

- `brand_subdomain` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- `byo_routing` (optional)
  Type: object
  
  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.
  
  - `mismatch` (optional)
    Type: boolean
  
  - `provider` (optional)
    Type: string; nullable
    
    The connected BYO provider, e.g. ses.
  
  - `bypassing_domains` (optional)
    Type: array
    
    Verified domains still sending through Nitrosend's hosted provider.
    
    Items:
      Type: string
  
  - `message` (optional)
    Type: string; nullable

- `subscribed_contacts_count` (optional)
  Type: integer
  
  Count of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.

- `logo_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `logo_tone` (optional)
  Type: string; nullable
  
  Measured from the logo. A light mark on transparent gets a header band in emails.
  
  enum: ["light","dark"]
  
  readOnly: true

- `logo_aspect` (optional)
  Type: number; nullable
  
  The logo's width over its height. Emails fit the logo to one header height.
  
  readOnly: true

- `screenshot_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `capabilities` (optional)
  Type: object
  
  Additional properties: true

- `sms_provisioned` (optional)
  Type: boolean
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Brand limit reached or validation failed

Content type: application/json

Type: unknown

oneOf:
  Type: object
  
  - `error` (required)
    Type: boolean
    
    const: true
  
  - `code` (required)
    Type: string
    
    Machine-readable reason returned when the current plan cannot create another brand.
    
    enum: ["brand_limit_reached"]
  
  - `message` (required)
    Type: string

  Type: unknown
  
  allOf:
    Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object
  
    Type: object
    
    - `validation_errors` (optional)
      Type: object
      
      Additional properties: 
        Type: array
        
        Items:
          Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "radius": 0,
  "spacing_density": "compact",
  "font_heading": "string",
  "font_body": "string",
  "heading_size": 12,
  "body_size": 12,
  "brand_document": "string",
  "company_description": "string",
  "physical_address": "string",
  "company_name": "string",
  "logo": "string",
  "email_from_name": "string",
  "email_from_email": "user@example.com",
  "email_reply_to": "user@example.com",
  "email_view_online": true,
  "email_view_online_placement": "top",
  "email_track_opens": true,
  "email_track_clicks": true,
  "test_email_recipients": [
    "user@example.com"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "radius": 0,
  "spacing_density": "compact",
  "font_heading": "string",
  "font_body": "string",
  "heading_size": 12,
  "body_size": 12,
  "brand_document": "string",
  "company_description": "string",
  "physical_address": "string",
  "company_name": "string",
  "logo": "string",
  "email_from_name": "string",
  "email_from_email": "user@example.com",
  "email_reply_to": "user@example.com",
  "email_view_online": true,
  "email_view_online_placement": "top",
  "email_track_opens": true,
  "email_track_clicks": true,
  "test_email_recipients": [
    "user@example.com"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "radius": 0,
  "spacing_density": "compact",
  "font_heading": "string",
  "font_body": "string",
  "heading_size": 12,
  "body_size": 12,
  "brand_document": "string",
  "company_description": "string",
  "physical_address": "string",
  "company_name": "string",
  "logo": "string",
  "email_from_name": "string",
  "email_from_email": "user@example.com",
  "email_reply_to": "user@example.com",
  "email_view_online": true,
  "email_view_online_placement": "top",
  "email_track_opens": true,
  "email_track_clicks": true,
  "test_email_recipients": [
    "user@example.com"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a brand

`GET /v1/my/brands/{sid}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Responses:

- 200: Brand

Content type: application/json

Type: object

Schema: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md)

- `id` (optional)
  Type: integer

- `sid` (optional)
  Type: string
  
  Public secure identifier (non-sequential)
  
  readOnly: true

- `account_id` (optional)
  Type: integer

- `brand_color` (optional)
  Type: string; nullable

- `text_color` (optional)
  Type: string; nullable

- `bg_color` (optional)
  Type: string; nullable

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string; nullable

- `font_body` (optional)
  Type: string; nullable

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string; nullable

- `default_header` (optional)
  Type: object; nullable

- `default_footer` (optional)
  Type: object; nullable

- `default_theme` (optional)
  Type: object; nullable

- `physical_address` (optional)
  Type: string; nullable

- `company_name` (optional)
  Type: string; nullable

- `source_url` (optional)
  Type: string; nullable

- `last_scraped_at` (optional)
  Type: string, date-time; nullable

- `links` (optional)
  Type: array; nullable
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `logo` (optional)
  Type: string; nullable
  
  Logo URL

- `complete` (optional)
  Type: boolean
  
  True when brand_color and company_name are set

- `email_from_name` (optional)
  Type: string; nullable

- `email_from_email` (optional)
  Type: string; nullable

- `email_reply_to` (optional)
  Type: string; nullable

- `from_email_domain_status` (optional)
  Type: string
  
  Authorization state of the configured visible From address.
  
  enum: ["blank","verified","unverified"]

- `effective_from_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_reply_to` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_sending_domain` (optional)
  Type: string; nullable
  
  readOnly: true

- `effective_source_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `sender_configured` (optional)
  Type: boolean
  
  readOnly: true

- `email_view_online` (optional)
  Type: boolean
  
  Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

- `email_view_online_placement` (optional)
  Type: string
  
  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.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  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_clicks` (optional)
  Type: boolean
  
  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_recipients` (optional)
  Type: array
  
  Items:
    Type: string, email

- `onboarding_state` (optional)
  Type: object
  
  JSONB — keys are step names, values are completion metadata
  
  Additional properties: true

- `onboarding` (optional)
  Type: object
  
  - `steps` (optional)
    Type: object
    
    Current state of each onboarding step
  
  - `progress` (optional)
    Type: object
    
    - `completed` (optional)
      Type: integer
    
    - `total` (optional)
      Type: integer

- `domain_verified` (optional)
  Type: boolean

- `can_send` (optional)
  Type: boolean

- `brand_subdomain` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- `byo_routing` (optional)
  Type: object
  
  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.
  
  - `mismatch` (optional)
    Type: boolean
  
  - `provider` (optional)
    Type: string; nullable
    
    The connected BYO provider, e.g. ses.
  
  - `bypassing_domains` (optional)
    Type: array
    
    Verified domains still sending through Nitrosend's hosted provider.
    
    Items:
      Type: string
  
  - `message` (optional)
    Type: string; nullable

- `subscribed_contacts_count` (optional)
  Type: integer
  
  Count of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.

- `logo_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `logo_tone` (optional)
  Type: string; nullable
  
  Measured from the logo. A light mark on transparent gets a header band in emails.
  
  enum: ["light","dark"]
  
  readOnly: true

- `logo_aspect` (optional)
  Type: number; nullable
  
  The logo's width over its height. Emails fit the logo to one header height.
  
  readOnly: true

- `screenshot_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `capabilities` (optional)
  Type: object
  
  Additional properties: true

- `sms_provisioned` (optional)
  Type: boolean
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a brand

`DELETE /v1/my/brands/{sid}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

- `force` (query, string, optional) - Must be `true` to delete a brand that has queued messages or scheduled/live campaigns.
  Type: string
  
  enum: ["true"]

Responses:

- 200: Deleted brand

Content type: application/json

Type: object

Schema: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md)

- `id` (optional)
  Type: integer

- `sid` (optional)
  Type: string
  
  Public secure identifier (non-sequential)
  
  readOnly: true

- `account_id` (optional)
  Type: integer

- `brand_color` (optional)
  Type: string; nullable

- `text_color` (optional)
  Type: string; nullable

- `bg_color` (optional)
  Type: string; nullable

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string; nullable

- `font_body` (optional)
  Type: string; nullable

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string; nullable

- `default_header` (optional)
  Type: object; nullable

- `default_footer` (optional)
  Type: object; nullable

- `default_theme` (optional)
  Type: object; nullable

- `physical_address` (optional)
  Type: string; nullable

- `company_name` (optional)
  Type: string; nullable

- `source_url` (optional)
  Type: string; nullable

- `last_scraped_at` (optional)
  Type: string, date-time; nullable

- `links` (optional)
  Type: array; nullable
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `logo` (optional)
  Type: string; nullable
  
  Logo URL

- `complete` (optional)
  Type: boolean
  
  True when brand_color and company_name are set

- `email_from_name` (optional)
  Type: string; nullable

- `email_from_email` (optional)
  Type: string; nullable

- `email_reply_to` (optional)
  Type: string; nullable

- `from_email_domain_status` (optional)
  Type: string
  
  Authorization state of the configured visible From address.
  
  enum: ["blank","verified","unverified"]

- `effective_from_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_reply_to` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_sending_domain` (optional)
  Type: string; nullable
  
  readOnly: true

- `effective_source_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `sender_configured` (optional)
  Type: boolean
  
  readOnly: true

- `email_view_online` (optional)
  Type: boolean
  
  Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

- `email_view_online_placement` (optional)
  Type: string
  
  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.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  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_clicks` (optional)
  Type: boolean
  
  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_recipients` (optional)
  Type: array
  
  Items:
    Type: string, email

- `onboarding_state` (optional)
  Type: object
  
  JSONB — keys are step names, values are completion metadata
  
  Additional properties: true

- `onboarding` (optional)
  Type: object
  
  - `steps` (optional)
    Type: object
    
    Current state of each onboarding step
  
  - `progress` (optional)
    Type: object
    
    - `completed` (optional)
      Type: integer
    
    - `total` (optional)
      Type: integer

- `domain_verified` (optional)
  Type: boolean

- `can_send` (optional)
  Type: boolean

- `brand_subdomain` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- `byo_routing` (optional)
  Type: object
  
  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.
  
  - `mismatch` (optional)
    Type: boolean
  
  - `provider` (optional)
    Type: string; nullable
    
    The connected BYO provider, e.g. ses.
  
  - `bypassing_domains` (optional)
    Type: array
    
    Verified domains still sending through Nitrosend's hosted provider.
    
    Items:
      Type: string
  
  - `message` (optional)
    Type: string; nullable

- `subscribed_contacts_count` (optional)
  Type: integer
  
  Count of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.

- `logo_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `logo_tone` (optional)
  Type: string; nullable
  
  Measured from the logo. A light mark on transparent gets a header band in emails.
  
  enum: ["light","dark"]
  
  readOnly: true

- `logo_aspect` (optional)
  Type: number; nullable
  
  The logo's width over its height. Emails fit the logo to one header height.
  
  readOnly: true

- `screenshot_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `capabilities` (optional)
  Type: object
  
  Additional properties: true

- `sms_provisioned` (optional)
  Type: boolean
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 409: Brand has active sends and requires explicit force confirmation

Content type: application/json

Type: object

- `error` (required)
  Type: boolean
  
  const: true

- `code` (required)
  Type: string
  
  enum: ["brand_has_active_sends"]

- `active_sends` (required)
  Reference: [BrandDeletionSafetyActiveSends](https://docs.nitrosend.com/api/schemas/branddeletionsafetyactivesends-7e42fa03b3.md); Type: object

- `deletion_safety` (required)
  Reference: [BrandDeletionSafety](https://docs.nitrosend.com/api/schemas/branddeletionsafety-6483c513a8.md); Type: object

- 422: Cannot delete the only brand

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/brands/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/brands/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a brand

`PATCH /v1/my/brands/{sid}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Request body: application/json (required)

Type: object

- `name` (optional)
  Type: string
  
  Internal brand name; mirrors company_name when company_name is omitted

- `brand_color` (optional)
  Type: string
  
  pattern: "^#[0-9a-fA-F]{6}$"

- `text_color` (optional)
  Type: string
  
  pattern: "^#[0-9a-fA-F]{6}$"

- `bg_color` (optional)
  Type: string
  
  pattern: "^#[0-9a-fA-F]{6}$"

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string

- `font_body` (optional)
  Type: string

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string

- `physical_address` (optional)
  Type: string

- `company_name` (optional)
  Type: string

- `logo` (optional)
  Type: string
  
  Signed blob ID or URL

- `email_from_name` (optional)
  Type: string

- `email_from_email` (optional)
  Type: string, email

- `email_reply_to` (optional)
  Type: string, email

- `email_view_online` (optional)
  Type: boolean

- `email_view_online_placement` (optional)
  Type: string
  
  Where the View in browser link goes: at the top of the email, or beside the footer's Unsubscribe link.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  Inject the open-tracking pixel into this brand's emails.

- `email_track_clicks` (optional)
  Type: boolean
  
  Rewrite this brand's links for click tracking.

- `sender_identity_id` (optional)
  Type: integer
  
  Ready brand-owned email sending identity to select through the canonical sender-selection authority.

- `sender_local_part` (optional)
  Type: string
  
  Visible From local part for the selected sending identity.

- `test_email_recipients` (optional)
  Type: array
  
  maxItems: 5
  
  Items:
    Type: string, email

- `links` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string, uri
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `default_header` (optional)
  Type: object
  
  Additional properties: true

- `default_footer` (optional)
  Type: object
  
  Additional properties: true

- `default_theme` (optional)
  Type: object
  
  Additional properties: true

Responses:

- 200: Updated brand

Content type: application/json

Type: object

Schema: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md)

- `id` (optional)
  Type: integer

- `sid` (optional)
  Type: string
  
  Public secure identifier (non-sequential)
  
  readOnly: true

- `account_id` (optional)
  Type: integer

- `brand_color` (optional)
  Type: string; nullable

- `text_color` (optional)
  Type: string; nullable

- `bg_color` (optional)
  Type: string; nullable

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string; nullable

- `font_body` (optional)
  Type: string; nullable

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string; nullable

- `default_header` (optional)
  Type: object; nullable

- `default_footer` (optional)
  Type: object; nullable

- `default_theme` (optional)
  Type: object; nullable

- `physical_address` (optional)
  Type: string; nullable

- `company_name` (optional)
  Type: string; nullable

- `source_url` (optional)
  Type: string; nullable

- `last_scraped_at` (optional)
  Type: string, date-time; nullable

- `links` (optional)
  Type: array; nullable
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `logo` (optional)
  Type: string; nullable
  
  Logo URL

- `complete` (optional)
  Type: boolean
  
  True when brand_color and company_name are set

- `email_from_name` (optional)
  Type: string; nullable

- `email_from_email` (optional)
  Type: string; nullable

- `email_reply_to` (optional)
  Type: string; nullable

- `from_email_domain_status` (optional)
  Type: string
  
  Authorization state of the configured visible From address.
  
  enum: ["blank","verified","unverified"]

- `effective_from_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_reply_to` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_sending_domain` (optional)
  Type: string; nullable
  
  readOnly: true

- `effective_source_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `sender_configured` (optional)
  Type: boolean
  
  readOnly: true

- `email_view_online` (optional)
  Type: boolean
  
  Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

- `email_view_online_placement` (optional)
  Type: string
  
  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.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  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_clicks` (optional)
  Type: boolean
  
  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_recipients` (optional)
  Type: array
  
  Items:
    Type: string, email

- `onboarding_state` (optional)
  Type: object
  
  JSONB — keys are step names, values are completion metadata
  
  Additional properties: true

- `onboarding` (optional)
  Type: object
  
  - `steps` (optional)
    Type: object
    
    Current state of each onboarding step
  
  - `progress` (optional)
    Type: object
    
    - `completed` (optional)
      Type: integer
    
    - `total` (optional)
      Type: integer

- `domain_verified` (optional)
  Type: boolean

- `can_send` (optional)
  Type: boolean

- `brand_subdomain` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- `byo_routing` (optional)
  Type: object
  
  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.
  
  - `mismatch` (optional)
    Type: boolean
  
  - `provider` (optional)
    Type: string; nullable
    
    The connected BYO provider, e.g. ses.
  
  - `bypassing_domains` (optional)
    Type: array
    
    Verified domains still sending through Nitrosend's hosted provider.
    
    Items:
      Type: string
  
  - `message` (optional)
    Type: string; nullable

- `subscribed_contacts_count` (optional)
  Type: integer
  
  Count of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.

- `logo_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `logo_tone` (optional)
  Type: string; nullable
  
  Measured from the logo. A light mark on transparent gets a header band in emails.
  
  enum: ["light","dark"]
  
  readOnly: true

- `logo_aspect` (optional)
  Type: number; nullable
  
  The logo's width over its height. Emails fit the logo to one header height.
  
  readOnly: true

- `screenshot_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `capabilities` (optional)
  Type: object
  
  Additional properties: true

- `sms_provisioned` (optional)
  Type: boolean
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/brands/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "radius": 0,
  "spacing_density": "compact",
  "font_heading": "string",
  "font_body": "string",
  "heading_size": 12,
  "body_size": 12,
  "brand_document": "string",
  "company_description": "string",
  "physical_address": "string",
  "company_name": "string",
  "logo": "string",
  "email_from_name": "string",
  "email_from_email": "user@example.com",
  "email_reply_to": "user@example.com",
  "email_view_online": true,
  "email_view_online_placement": "top",
  "email_track_opens": true,
  "email_track_clicks": true,
  "sender_identity_id": 0,
  "sender_local_part": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}'
```

### JavaScript

```javascript
const body = `{
  "name": "string",
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "radius": 0,
  "spacing_density": "compact",
  "font_heading": "string",
  "font_body": "string",
  "heading_size": 12,
  "body_size": 12,
  "brand_document": "string",
  "company_description": "string",
  "physical_address": "string",
  "company_name": "string",
  "logo": "string",
  "email_from_name": "string",
  "email_from_email": "user@example.com",
  "email_reply_to": "user@example.com",
  "email_view_online": true,
  "email_view_online_placement": "top",
  "email_track_opens": true,
  "email_track_clicks": true,
  "sender_identity_id": 0,
  "sender_local_part": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "name": "string",
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "radius": 0,
  "spacing_density": "compact",
  "font_heading": "string",
  "font_body": "string",
  "heading_size": 12,
  "body_size": 12,
  "brand_document": "string",
  "company_description": "string",
  "physical_address": "string",
  "company_name": "string",
  "logo": "string",
  "email_from_name": "string",
  "email_from_email": "user@example.com",
  "email_reply_to": "user@example.com",
  "email_view_online": true,
  "email_view_online_placement": "top",
  "email_track_opens": true,
  "email_track_clicks": true,
  "sender_identity_id": 0,
  "sender_local_part": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/brands/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Reserve and prepare the Nitrosend sender

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Request body: application/json

Type: object

- `subdomain` (optional)
  Type: string
  
  Chosen subdomain label under the hosted apex; validated by the same policy as company-derived names.

- `local_part` (optional)
  Type: string
  
  Local part for the sender address (defaults to `hello`).

Responses:

- 200: The brand-subdomain sender is ready

Content type: application/json

Type: object

Schema: [BrandSubdomainPreparationResponse](https://docs.nitrosend.com/api/schemas/brandsubdomainpreparationresponse-760add0860.md)

- `status` (required)
  Type: string
  
  enum: ["ready","unavailable"]

- `brand_subdomain` (required)
  Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- 422: 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`.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 429: Address request rate or claim allowance reached. Retry-After specifies the wait in seconds.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: The shared hosted-sender root is not release-ready; no identity or delivery state was written

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/prepare_sending' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "subdomain": "string",
  "local_part": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "subdomain": "string",
  "local_part": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/prepare_sending', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "subdomain": "string",
  "local_part": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/prepare_sending',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Change the brand's Nitrosend address name

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Request body: application/json (required)

Type: object

- `subdomain` (required)
  Type: string
  
  Requested hosted address name
  
  maxLength: 63

- `expected_fqdn` (required)
  Type: string
  
  Current brand_subdomain.fqdn

Additional properties: false

Responses:

- 200: Updated brand; an exact retry returns the same address

Content type: application/json

Type: object

Schema: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md)

- `id` (optional)
  Type: integer

- `sid` (optional)
  Type: string
  
  Public secure identifier (non-sequential)
  
  readOnly: true

- `account_id` (optional)
  Type: integer

- `brand_color` (optional)
  Type: string; nullable

- `text_color` (optional)
  Type: string; nullable

- `bg_color` (optional)
  Type: string; nullable

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string; nullable

- `font_body` (optional)
  Type: string; nullable

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string; nullable

- `default_header` (optional)
  Type: object; nullable

- `default_footer` (optional)
  Type: object; nullable

- `default_theme` (optional)
  Type: object; nullable

- `physical_address` (optional)
  Type: string; nullable

- `company_name` (optional)
  Type: string; nullable

- `source_url` (optional)
  Type: string; nullable

- `last_scraped_at` (optional)
  Type: string, date-time; nullable

- `links` (optional)
  Type: array; nullable
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `logo` (optional)
  Type: string; nullable
  
  Logo URL

- `complete` (optional)
  Type: boolean
  
  True when brand_color and company_name are set

- `email_from_name` (optional)
  Type: string; nullable

- `email_from_email` (optional)
  Type: string; nullable

- `email_reply_to` (optional)
  Type: string; nullable

- `from_email_domain_status` (optional)
  Type: string
  
  Authorization state of the configured visible From address.
  
  enum: ["blank","verified","unverified"]

- `effective_from_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_reply_to` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_sending_domain` (optional)
  Type: string; nullable
  
  readOnly: true

- `effective_source_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `sender_configured` (optional)
  Type: boolean
  
  readOnly: true

- `email_view_online` (optional)
  Type: boolean
  
  Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

- `email_view_online_placement` (optional)
  Type: string
  
  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.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  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_clicks` (optional)
  Type: boolean
  
  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_recipients` (optional)
  Type: array
  
  Items:
    Type: string, email

- `onboarding_state` (optional)
  Type: object
  
  JSONB — keys are step names, values are completion metadata
  
  Additional properties: true

- `onboarding` (optional)
  Type: object
  
  - `steps` (optional)
    Type: object
    
    Current state of each onboarding step
  
  - `progress` (optional)
    Type: object
    
    - `completed` (optional)
      Type: integer
    
    - `total` (optional)
      Type: integer

- `domain_verified` (optional)
  Type: boolean

- `can_send` (optional)
  Type: boolean

- `brand_subdomain` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- `byo_routing` (optional)
  Type: object
  
  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.
  
  - `mismatch` (optional)
    Type: boolean
  
  - `provider` (optional)
    Type: string; nullable
    
    The connected BYO provider, e.g. ses.
  
  - `bypassing_domains` (optional)
    Type: array
    
    Verified domains still sending through Nitrosend's hosted provider.
    
    Items:
      Type: string
  
  - `message` (optional)
    Type: string; nullable

- `subscribed_contacts_count` (optional)
  Type: integer
  
  Count of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.

- `logo_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `logo_tone` (optional)
  Type: string; nullable
  
  Measured from the logo. A light mark on transparent gets a header band in emails.
  
  enum: ["light","dark"]
  
  readOnly: true

- `logo_aspect` (optional)
  Type: number; nullable
  
  The logo's width over its height. Emails fit the logo to one header height.
  
  readOnly: true

- `screenshot_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `capabilities` (optional)
  Type: object
  
  Additional properties: true

- `sms_provisioned` (optional)
  Type: boolean
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 409: The address changed, or affected delivery work is still active. Nothing was changed.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: The name is prohibited or taken, the account allowance is exhausted, or the inbox cannot preserve more addresses. Nothing was changed.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 429: Request or claim rate exceeded. Retry-After specifies the wait in seconds.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: The shared service is unavailable. Nothing was changed.

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/rename_hosted_sender' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "subdomain": "string",
  "expected_fqdn": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "subdomain": "string",
  "expected_fqdn": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/rename_hosted_sender', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "subdomain": "string",
  "expected_fqdn": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/rename_hosted_sender',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Check whether a Nitrosend address can be reserved

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

- `subdomain` (query, string, required) - Requested subdomain label under the hosted apex
  Type: string

- `local_part` (query, string, optional) - Requested local part, checked with the same policy reservation applies; omitted means the allocator's default.
  Type: string

Responses:

- 200: Availability result

Content type: application/json

Type: object

Schema: [HostedSenderAvailability](https://docs.nitrosend.com/api/schemas/hostedsenderavailability-ac1d44a545.md)

- `subdomain` (required)
  Type: string
  
  The normalised label that would be reserved (or the input when unsafe)

- `fqdn` (optional)
  Type: string; nullable

- `available` (required)
  Type: boolean

- `reason` (optional)
  Type: string; nullable
  
  Why the address is unavailable; null when available
  
  enum: ["taken","unsafe","reserved","local_part_invalid"]

- `local_part` (optional)
  Type: string; nullable
  
  The normalised local part that would be reserved (the allocator's default when none was given), or the input when it is invalid.

- `from_email` (optional)
  Type: string; nullable
  
  The exact address that would be reserved; null when unavailable for a policy reason

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands/string/hosted_sender_availability?subdomain=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/hosted_sender_availability?subdomain=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands/string/hosted_sender_availability?subdomain=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get deletion safety for a brand

`GET /v1/my/brands/{sid}/deletion_safety`

Returns authoritative deletion impact counts and active-send state for the confirmation UI.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Responses:

- 200: Brand deletion safety

Content type: application/json

Type: object

Schema: [BrandDeletionSafety](https://docs.nitrosend.com/api/schemas/branddeletionsafety-6483c513a8.md)

- `deletion_impact` (required)
  Reference: [BrandDeletionSafetyImpact](https://docs.nitrosend.com/api/schemas/branddeletionsafetyimpact-849b0a5a1d.md); Type: object

- `active_sends` (required)
  Reference: [BrandDeletionSafetyActiveSends](https://docs.nitrosend.com/api/schemas/branddeletionsafetyactivesends-7e42fa03b3.md); Type: object

- `can_delete` (required)
  Type: boolean
  
  True when no force confirmation is required.

- `requires_force` (required)
  Type: boolean
  
  True when active sends require `force=true` to delete.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands/string/deletion_safety' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/deletion_safety', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands/string/deletion_safety',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Scan a business website and apply its Brand Kit

`POST /v1/my/brands/{sid}/scrape`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

- `Idempotency-Key` (header, string, optional) - Reuse only for an exact retry of this website request.
  Type: string
  
  maxLength: 128

Request body: application/json (required)

Type: object

Schema: [BrandWebsiteInput](https://docs.nitrosend.com/api/schemas/brandwebsiteinput-e152cc1e28.md)

- `url` (required)
  Type: string
  
  Real business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.

Responses:

- 202: Admitted scan, including the same reference on an idempotent retry

Content type: application/json

Type: object

Schema: [BrandScanAdmission](https://docs.nitrosend.com/api/schemas/brandscanadmission-c86217fed3.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","scraping"]

- `url` (required)
  Type: string

- `scan_id` (required)
  Type: string

- `idempotent_replay` (optional)
  Type: boolean

- 400: Invalid idempotency key

- 409: Idempotency key already used for another website

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/scrape' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "url": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "url": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/scrape', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "url": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/scrape',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get brand onboarding state

`GET /v1/my/brands/{sid}/onboarding`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Responses:

- 200: Onboarding state for the brand

Content type: application/json

Type: object

- `steps` (optional)
  Type: object
  
  Current state of each onboarding step

- `progress` (optional)
  Type: object
  
  - `completed` (optional)
    Type: integer
  
  - `total` (optional)
    Type: integer

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands/string/onboarding' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/onboarding', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands/string/onboarding',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Complete a brand onboarding step

`POST /v1/my/brands/{sid}/onboarding/steps`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Request body: application/json (required)

Type: object

- `step` (required)
  Type: string
  
  enum: ["brand_kit_setup","domain_verified","first_contact","first_send"]

Responses:

- 200: Updated onboarding state

Content type: application/json

Type: object

- `steps` (optional)
  Type: object

- `progress` (optional)
  Type: object
  
  - `completed` (optional)
    Type: integer
  
  - `total` (optional)
    Type: integer

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/onboarding/steps' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "step": "brand_kit_setup"
}'
```

### JavaScript

```javascript
const body = `{
  "step": "brand_kit_setup"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/onboarding/steps', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "step": "brand_kit_setup"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/onboarding/steps',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Start a website preview

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

- `Idempotency-Key` (header, string, optional) - Reuse only for an exact retry of this website request.
  Type: string
  
  maxLength: 128

Request body: application/json (required)

Type: object

Schema: [BrandWebsiteInput](https://docs.nitrosend.com/api/schemas/brandwebsiteinput-e152cc1e28.md)

- `url` (required)
  Type: string
  
  Real business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.

Responses:

- 202: Admitted preview

Content type: application/json

Type: object

Schema: [BrandScanAdmission](https://docs.nitrosend.com/api/schemas/brandscanadmission-c86217fed3.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","scraping"]

- `url` (required)
  Type: string

- `scan_id` (required)
  Type: string

- `idempotent_replay` (optional)
  Type: boolean

- 400: Invalid idempotency key

- 409: Idempotency key already used for another website

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/scrape_preview' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "url": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "url": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/scrape_preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "url": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/scrape_preview',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Read the named or current brand scan

`GET /v1/my/brands/{sid}/scrape_preview_status`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

- `scan_id` (query, string, optional) - Omit to recover this brand's current admitted scan. The reference survives transient progress-cache expiry.
  Type: string

Responses:

- 200: Current transient scan result

Content type: application/json

Type: object

Schema: [BrandScanStatus](https://docs.nitrosend.com/api/schemas/brandscanstatus-63f98dd6f9.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","completed","failed","unknown"]

- `scan_id` (required)
  Type: string; nullable

- `kind` (optional)
  Type: string
  
  enum: ["website","kit"]

- `url` (optional)
  Type: string

- `error` (optional)
  Type: string

- `preview` (optional)
  Type: object
  
  Additional properties: true

- 404: Unknown or expired progress. The setup center retains any admitted reference.

Content type: application/json

Type: object

Schema: [BrandScanStatus](https://docs.nitrosend.com/api/schemas/brandscanstatus-63f98dd6f9.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","completed","failed","unknown"]

- `scan_id` (required)
  Type: string; nullable

- `kind` (optional)
  Type: string
  
  enum: ["website","kit"]

- `url` (optional)
  Type: string

- `error` (optional)
  Type: string

- `preview` (optional)
  Type: object
  
  Additional properties: true

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands/string/scrape_preview_status' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/scrape_preview_status', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands/string/scrape_preview_status',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Apply a selected website or file kit preview

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Request body: application/json (required)

Type: object

- `scan_id` (required)
  Type: string

- `fields` (optional)
  Type: object
  
  Selected editable Brand Kit fields. Unselected captured fields are not applied.
  
  Additional properties: true

- `include_logo` (optional)
  Type: boolean
  
  Attach the website preview's captured logo.
  
  default: false

- `logo` (optional)
  Type: string
  
  A signed uploaded logo blob, overriding the preview logo.

- `logo_candidate_id` (optional)
  Type: string
  
  Selected candidate from a file kit preview.

- `template_id` (optional)
  Type: string
  
  Selected template from a file kit preview.

Responses:

- 200: Selected kit saved atomically

Content type: application/json

Type: object

- `brand` (required)
  Reference: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md); Type: object

- `template` (optional)
  Type: object
  
  Additional properties: true

- 409: A newer source superseded this save

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 503: Logo rendering is temporarily unavailable

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/kit_apply' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "scan_id": "string",
  "fields": {},
  "include_logo": false,
  "logo": "string",
  "logo_candidate_id": "string",
  "template_id": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "scan_id": "string",
  "fields": {},
  "include_logo": false,
  "logo": "string",
  "logo_candidate_id": "string",
  "template_id": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/kit_apply', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "scan_id": "string",
  "fields": {},
  "include_logo": false,
  "logo": "string",
  "logo_candidate_id": "string",
  "template_id": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/kit_apply',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Email the account owner a one-time sign-in link

`POST /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.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

- `Idempotency-Key` (header, string, required)
  Type: string

Responses:

- 202: Accepted

- 400: Missing idempotency key

- 403: Not the account owner, or past the first week

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/sign_in_link' \
  -H 'Idempotency-Key: string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/sign_in_link', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/sign_in_link',
    headers={
        'Idempotency-Key': 'string',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Sign in with a one-time link

`POST /v1/sign_in_links/consume`

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `token` (required)
  Type: string

Responses:

- 200: A session token and the account and brand to open

- 404: Not a link we issued

- 410: Expired or already used

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/sign_in_links/consume' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "token": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "token": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/sign_in_links/consume', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "token": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/sign_in_links/consume',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Send a fresh link to the owner of an expired one

`POST /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.

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `token` (required)
  Type: string

Responses:

- 202: Accepted

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/sign_in_links/resend' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "token": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "token": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/sign_in_links/resend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "token": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/sign_in_links/resend',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Ask for the brand's welcome email

`POST /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`.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Responses:

- 202: Setup center state, with the welcome email's progress

Content type: application/json

Type: object

Schema: [SetupCenterPayload](https://docs.nitrosend.com/api/schemas/setupcenterpayload-84155dd467.md)

- `next_actions` (optional)
  Type: array
  
  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.
  
  Items:
    Type: object
    
    - `id` (required)
      Type: string
      
      enum: ["brand","sender","address","contacts","custom_domain","agent"]
    
    - `blocking` (required)
      Type: boolean
    
    - `scope` (optional)
      Type: string
      
      enum: ["email","campaigns_and_flows"]
    
    - `state` (required)
      Type: string
      
      enum: ["action_required","recommended","waiting"]

- `cards` (optional)
  Type: array
  
  Items:
    Reference: [SetupCenterCard](https://docs.nitrosend.com/api/schemas/setupcentercard-299d2987e3.md); Type: object

- `sections` (optional)
  Type: object
  
  - `required` (optional)
    Type: array
    
    Items:
      Type: string
  
  - `recommended` (optional)
    Type: array
    
    Items:
      Type: string

- `progress` (optional)
  Type: object
  
  Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.
  
  - `completed` (optional)
    Type: integer
  
  - `total` (optional)
    Type: integer

- `seen` (optional)
  Type: boolean

- `dismissed` (optional)
  Type: boolean

- `complete` (optional)
  Type: boolean

- `established` (optional)
  Type: boolean
  
  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_email` (optional)
  Type: object; nullable
  
  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.
  
  - `state` (optional)
    Type: string
    
    `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.
    
    enum: ["queued","writing","sending","sent","written","skipped","failed"]
  
  - `campaign_id` (optional)
    Type: integer; nullable
  
  - `sent_at` (optional)
    Type: string, date-time; nullable
  
  - `to` (optional)
    Type: string; nullable

- `suggested_site` (optional)
  Type: string; nullable
  
  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_choice` (optional)
  Type: string; nullable
  
  Who a first real send comes from, once asked.
  
  enum: ["own","hosted"]

- `contact_source` (optional)
  Type: object; nullable
  
  The mail tools the last scan found evidence of on the brand's site.
  
  - `site` (optional)
    Type: string
  
  - `tools` (optional)
    Type: array
    
    Items:
      Type: string
      
      enum: ["mailchimp","klaviyo","hubspot","mailerlite","brevo","activecampaign","shopify"]

- `suggested_address` (optional)
  Type: object; nullable
  
  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.
  
  - `site` (optional)
    Type: string
  
  - `address` (optional)
    Type: string
  
  - `page` (optional)
    Type: string
    
    Where on the site it was found, as host and path (allbirds.com/pages/contact).

- `first_kit` (optional)
  Type: boolean
  
  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.
  
  readOnly: true

- `can_email_sign_in_link` (optional)
  Type: boolean
  
  Present on authenticated UI snapshots. Whether this requester is the fresh account owner eligible to request the saved draft link; the command rechecks authorization and draft ownership.
  
  readOnly: true

- `current_scan` (optional)
  Type: object; nullable
  
  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.
  
  - `scan_id` (required)
    Type: string
  
  - `kind` (required)
    Type: string
    
    enum: ["website","kit","brief"]
  
  - `url` (optional)
    Type: string
  
  - `started_at` (required)
    Type: string, date-time
  
  - `status` (required)
    Type: string
    
    enum: ["scanning","completed","failed","unknown"]
  
  - `applied` (required)
    Type: boolean
  
  - `error` (optional)
    Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/brands/string/welcome_email' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/welcome_email', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/brands/string/welcome_email',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get brand setup center state

`GET /v1/my/brands/{sid}/setup_center`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Responses:

- 200: Setup center state for the brand

Content type: application/json

Type: object

Schema: [SetupCenterPayload](https://docs.nitrosend.com/api/schemas/setupcenterpayload-84155dd467.md)

- `next_actions` (optional)
  Type: array
  
  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.
  
  Items:
    Type: object
    
    - `id` (required)
      Type: string
      
      enum: ["brand","sender","address","contacts","custom_domain","agent"]
    
    - `blocking` (required)
      Type: boolean
    
    - `scope` (optional)
      Type: string
      
      enum: ["email","campaigns_and_flows"]
    
    - `state` (required)
      Type: string
      
      enum: ["action_required","recommended","waiting"]

- `cards` (optional)
  Type: array
  
  Items:
    Reference: [SetupCenterCard](https://docs.nitrosend.com/api/schemas/setupcentercard-299d2987e3.md); Type: object

- `sections` (optional)
  Type: object
  
  - `required` (optional)
    Type: array
    
    Items:
      Type: string
  
  - `recommended` (optional)
    Type: array
    
    Items:
      Type: string

- `progress` (optional)
  Type: object
  
  Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.
  
  - `completed` (optional)
    Type: integer
  
  - `total` (optional)
    Type: integer

- `seen` (optional)
  Type: boolean

- `dismissed` (optional)
  Type: boolean

- `complete` (optional)
  Type: boolean

- `established` (optional)
  Type: boolean
  
  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_email` (optional)
  Type: object; nullable
  
  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.
  
  - `state` (optional)
    Type: string
    
    `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.
    
    enum: ["queued","writing","sending","sent","written","skipped","failed"]
  
  - `campaign_id` (optional)
    Type: integer; nullable
  
  - `sent_at` (optional)
    Type: string, date-time; nullable
  
  - `to` (optional)
    Type: string; nullable

- `suggested_site` (optional)
  Type: string; nullable
  
  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_choice` (optional)
  Type: string; nullable
  
  Who a first real send comes from, once asked.
  
  enum: ["own","hosted"]

- `contact_source` (optional)
  Type: object; nullable
  
  The mail tools the last scan found evidence of on the brand's site.
  
  - `site` (optional)
    Type: string
  
  - `tools` (optional)
    Type: array
    
    Items:
      Type: string
      
      enum: ["mailchimp","klaviyo","hubspot","mailerlite","brevo","activecampaign","shopify"]

- `suggested_address` (optional)
  Type: object; nullable
  
  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.
  
  - `site` (optional)
    Type: string
  
  - `address` (optional)
    Type: string
  
  - `page` (optional)
    Type: string
    
    Where on the site it was found, as host and path (allbirds.com/pages/contact).

- `first_kit` (optional)
  Type: boolean
  
  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.
  
  readOnly: true

- `can_email_sign_in_link` (optional)
  Type: boolean
  
  Present on authenticated UI snapshots. Whether this requester is the fresh account owner eligible to request the saved draft link; the command rechecks authorization and draft ownership.
  
  readOnly: true

- `current_scan` (optional)
  Type: object; nullable
  
  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.
  
  - `scan_id` (required)
    Type: string
  
  - `kind` (required)
    Type: string
    
    enum: ["website","kit","brief"]
  
  - `url` (optional)
    Type: string
  
  - `started_at` (required)
    Type: string, date-time
  
  - `status` (required)
    Type: string
    
    enum: ["scanning","completed","failed","unknown"]
  
  - `applied` (required)
    Type: boolean
  
  - `error` (optional)
    Type: string

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/brands/string/setup_center' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/setup_center', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/brands/string/setup_center',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update brand setup center state

`PATCH /v1/my/brands/{sid}/setup_center`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `sid` (path, string, required) - Brand secure identifier
  Type: string

Request body: application/json (required)

Type: object

Provide one of `seen`, `dismissed`, `sender_choice`, or `card`.

- `seen` (optional)
  Type: boolean

- `dismissed` (optional)
  Type: boolean

- `sender_choice` (optional)
  Type: string
  
  enum: ["own","hosted"]

- `card` (optional)
  Type: string
  
  enum: ["brand_kit_scan","import_subscribers","first_email","connect_agent","dns"]

- `metadata` (optional)
  Type: object
  
  Additional properties: true

Responses:

- 200: Updated setup center state

Content type: application/json

Type: object

Schema: [SetupCenterPayload](https://docs.nitrosend.com/api/schemas/setupcenterpayload-84155dd467.md)

- `next_actions` (optional)
  Type: array
  
  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.
  
  Items:
    Type: object
    
    - `id` (required)
      Type: string
      
      enum: ["brand","sender","address","contacts","custom_domain","agent"]
    
    - `blocking` (required)
      Type: boolean
    
    - `scope` (optional)
      Type: string
      
      enum: ["email","campaigns_and_flows"]
    
    - `state` (required)
      Type: string
      
      enum: ["action_required","recommended","waiting"]

- `cards` (optional)
  Type: array
  
  Items:
    Reference: [SetupCenterCard](https://docs.nitrosend.com/api/schemas/setupcentercard-299d2987e3.md); Type: object

- `sections` (optional)
  Type: object
  
  - `required` (optional)
    Type: array
    
    Items:
      Type: string
  
  - `recommended` (optional)
    Type: array
    
    Items:
      Type: string

- `progress` (optional)
  Type: object
  
  Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.
  
  - `completed` (optional)
    Type: integer
  
  - `total` (optional)
    Type: integer

- `seen` (optional)
  Type: boolean

- `dismissed` (optional)
  Type: boolean

- `complete` (optional)
  Type: boolean

- `established` (optional)
  Type: boolean
  
  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_email` (optional)
  Type: object; nullable
  
  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.
  
  - `state` (optional)
    Type: string
    
    `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.
    
    enum: ["queued","writing","sending","sent","written","skipped","failed"]
  
  - `campaign_id` (optional)
    Type: integer; nullable
  
  - `sent_at` (optional)
    Type: string, date-time; nullable
  
  - `to` (optional)
    Type: string; nullable

- `suggested_site` (optional)
  Type: string; nullable
  
  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_choice` (optional)
  Type: string; nullable
  
  Who a first real send comes from, once asked.
  
  enum: ["own","hosted"]

- `contact_source` (optional)
  Type: object; nullable
  
  The mail tools the last scan found evidence of on the brand's site.
  
  - `site` (optional)
    Type: string
  
  - `tools` (optional)
    Type: array
    
    Items:
      Type: string
      
      enum: ["mailchimp","klaviyo","hubspot","mailerlite","brevo","activecampaign","shopify"]

- `suggested_address` (optional)
  Type: object; nullable
  
  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.
  
  - `site` (optional)
    Type: string
  
  - `address` (optional)
    Type: string
  
  - `page` (optional)
    Type: string
    
    Where on the site it was found, as host and path (allbirds.com/pages/contact).

- `first_kit` (optional)
  Type: boolean
  
  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.
  
  readOnly: true

- `can_email_sign_in_link` (optional)
  Type: boolean
  
  Present on authenticated UI snapshots. Whether this requester is the fresh account owner eligible to request the saved draft link; the command rechecks authorization and draft ownership.
  
  readOnly: true

- `current_scan` (optional)
  Type: object; nullable
  
  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.
  
  - `scan_id` (required)
    Type: string
  
  - `kind` (required)
    Type: string
    
    enum: ["website","kit","brief"]
  
  - `url` (optional)
    Type: string
  
  - `started_at` (required)
    Type: string, date-time
  
  - `status` (required)
    Type: string
    
    enum: ["scanning","completed","failed","unknown"]
  
  - `applied` (required)
    Type: boolean
  
  - `error` (optional)
    Type: string

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/brands/string/setup_center' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seen": true,
  "dismissed": true,
  "sender_choice": "own",
  "card": "brand_kit_scan",
  "metadata": {}
}'
```

### JavaScript

```javascript
const body = `{
  "seen": true,
  "dismissed": true,
  "sender_choice": "own",
  "card": "brand_kit_scan",
  "metadata": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/brands/string/setup_center', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "seen": true,
  "dismissed": true,
  "sender_choice": "own",
  "card": "brand_kit_scan",
  "metadata": {}
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/brands/string/setup_center',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List messages

`GET /v1/my/messages`

Returns all messages by default. Use source_type to narrow to campaign,
flow, transactional, or test sends.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `source_type` (query, string, optional) - Filter by source. Omit or use 'all' for everything.
  Type: string
  
  enum: ["all","campaign","flow","transactional","test"]

- `flow_id` (query, integer, optional) - Filter to messages from a specific flow
  Type: integer

- `campaign_id` (query, integer, optional) - Filter to messages from a specific campaign
  Type: integer

- `date` (query, string, date, optional) - Filter to messages created on this date
  Type: string, date

- `channel` (query, string, optional)
  Type: string
  
  enum: ["email","sms"]

- `status` (query, string, optional)
  Type: string
  
  enum: ["queued","sent","failed"]

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated list of messages

Content type: application/json

Type: array

Items:
  Reference: [Message](https://docs.nitrosend.com/api/schemas/message-2f77668a9d.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/messages?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/messages?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/messages?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Send a transactional message

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `Idempotency-Key` (header, string, optional) - 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.

  Type: string

Request body: application/json (required)

Type: object

- `channel` (required)
  Type: string
  
  enum: ["email","sms"]

- `to` (required)
  Type: string
  
  Recipient email address or E.164 phone number

- `cc` (optional)
  Type: array
  
  Visible email copies. Each distinct recipient consumes an email credit, daily allowance and sending capacity. Email only.
  
  maxItems: 10
  
  Items:
    Type: string, email

- `bcc` (optional)
  Type: array
  
  Hidden email copies, omitted from delivered headers. Counted toward usage just like To and Cc. Email only.
  
  maxItems: 10
  
  Items:
    Type: string, email

- `subject` (optional)
  Type: string
  
  Email subject line (required for email channel)

- `body` (optional)
  Type: string
  
  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`.
  

- `html` (optional)
  Type: string
  
  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_id` (optional)
  Type: integer
  
  Load email design from an existing template (email only)

- `contact_id` (optional)
  Type: integer
  
  Optional contact to personalize with when rendering a template

- `from` (optional)
  Type: string
  
  Verified sender email for this email message. May include a display name, for example "Acme <hello@example.com>".
  

- `from_email` (optional)
  Type: string
  
  Verified sender email for this email message. Alias of `from`.

- `from_name` (optional)
  Type: string
  
  Sender display name for this email message

- `reply_to` (optional)
  Type: string
  
  Reply-to email address for this email message

- `headers` (optional)
  Type: object
  
  Provider headers for this email message. Structural and Nitrosend-reserved headers are rejected.
  
  
  Additional properties: 
    Type: string

- `tags` (optional)
  Type: object
  
  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.
  
  
  Additional properties: 
    Type: string

- `data` (optional)
  Type: object
  
  Merge variables
  
  Additional properties: true

- `mail_action` (optional)
  Reference: [MailActionDescription](https://docs.nitrosend.com/api/schemas/mailactiondescription-e8c6bf32cc.md); Type: object
  
  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.
  

- `idempotency_key` (optional)
  Type: string
  
  Stable idempotency key (alternative to the header). One of the two is required.
  
  
  minLength: 1

Responses:

- 200: Existing message returned for idempotency replay

Content type: application/json

Type: MessageSendResult

Schema: [MessageSendResult](https://docs.nitrosend.com/api/schemas/messagesendresult-ff26fd2684.md)

allOf:
  Reference: [Message](https://docs.nitrosend.com/api/schemas/message-2f77668a9d.md); Type: object

  Type: object
  
  - `ignored_fields` (required)
    Type: array
    
    Top-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.
    
    
    Items:
      Type: string

- 201: Message created

Content type: application/json

Type: MessageSendResult

Schema: [MessageSendResult](https://docs.nitrosend.com/api/schemas/messagesendresult-ff26fd2684.md)

allOf:
  Reference: [Message](https://docs.nitrosend.com/api/schemas/message-2f77668a9d.md); Type: object

  Type: object
  
  - `ignored_fields` (required)
    Type: array
    
    Top-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.
    
    
    Items:
      Type: string

- 400: Missing idempotency key (`idempotency_key_required`).

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 402: 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.

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `code` (optional)
    Type: integer
    
    const: 402
  
  - `error_code` (required)
    Type: string
    
    enum: ["plan_required"]
  
  - `how_to_fix` (required)
    Type: string
  
  - `plan_url` (required)
    Type: string, uri

- 409: Idempotency conflict or explicit sender selection required; no new message is retained in either case

Content type: application/json

Type: unknown

oneOf:
  Type: object
  
  - `code` (optional)
    Type: integer
    
    Example:
    
    ```json
    409
    ```
  
  - `message` (optional)
    Type: string
  
  - `error` (optional)
    Type: boolean
    
    Example:
    
    ```json
    true
    ```
  
  - `error_code` (optional)
    Type: string
    
    enum: ["idempotency_conflict"]

  Type: object
  
  - `code` (required)
    Type: string
    
    enum: ["sender_identity_selection_required"]
  
  - `message` (required)
    Type: string
  
  - `error` (required)
    Type: boolean
    
    const: true
  
  - `error_code` (required)
    Type: string
    
    enum: ["sender_identity_selection_required"]
  
  - `retryable` (required)
    Type: boolean
  
  - `brand_subdomain` (required)
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- 422: 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`.


Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string
  
  - `ignored_fields` (optional)
    Type: array
    
    Items:
      Type: string

  Reference: [SendRefusalDetail](https://docs.nitrosend.com/api/schemas/sendrefusaldetail-6a89f2dddc.md); Type: 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).
  

- 503: Admission evidence or the shared hosted-sender root is temporarily unavailable

Content type: application/json

Type: unknown

oneOf:
  Type: unknown
  
  allOf:
    Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object
  
    Type: object
    
    - `error_code` (required)
      Type: string
      
      enum: ["delivery_evidence_pending"]
    
    - `retryable` (required)
      Type: boolean
      
      const: true
    
    - `retry_at` (required)
      Type: string, date-time

  Type: object
  
  - `code` (required)
    Type: string
    
    enum: ["hosted_sender_root_unavailable"]
  
  - `message` (required)
    Type: string
  
  - `error` (required)
    Type: boolean
    
    const: true
  
  - `error_code` (required)
    Type: string
    
    enum: ["hosted_sender_root_unavailable"]
  
  - `retryable` (required)
    Type: boolean
    
    const: true
  
  - `brand_subdomain` (required)
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/messages' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "email",
  "to": "string",
  "cc": [
    "user@example.com"
  ],
  "bcc": [
    "user@example.com"
  ],
  "subject": "string",
  "body": "string",
  "html": "string",
  "template_id": 0,
  "contact_id": 0,
  "from": "string",
  "from_email": "string",
  "from_name": "string",
  "reply_to": "string",
  "headers": {},
  "tags": {},
  "data": {},
  "mail_action": {
    "@context": "https://mailschema.org/contexts/map-0.3.jsonld",
    "@type": "MailAction",
    "@id": "https://example.com",
    "profile": "https://mailschema.org/profiles/map/0.3",
    "type": {
      "id": "https://example.com",
      "version": "string",
      "contractDigest": "string"
    },
    "issuedAt": "2024-01-15T09:30:00Z",
    "expiresAt": "2024-01-15T09:30:00Z",
    "inLanguage": "string",
    "service": {
      "id": "https://example.com",
      "tenant": "https://example.com"
    },
    "recipient": "user@example.com",
    "subject": {
      "id": "https://example.com",
      "title": "string"
    },
    "terms": {
      "id": "https://example.com",
      "version": "string"
    },
    "details": {},
    "operations": [
      {
        "id": "string",
        "capability": {}
      }
    ],
    "human": {
      "url": "https://example.com"
    }
  },
  "idempotency_key": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "channel": "email",
  "to": "string",
  "cc": [
    "user@example.com"
  ],
  "bcc": [
    "user@example.com"
  ],
  "subject": "string",
  "body": "string",
  "html": "string",
  "template_id": 0,
  "contact_id": 0,
  "from": "string",
  "from_email": "string",
  "from_name": "string",
  "reply_to": "string",
  "headers": {},
  "tags": {},
  "data": {},
  "mail_action": {
    "@context": "https://mailschema.org/contexts/map-0.3.jsonld",
    "@type": "MailAction",
    "@id": "https://example.com",
    "profile": "https://mailschema.org/profiles/map/0.3",
    "type": {
      "id": "https://example.com",
      "version": "string",
      "contractDigest": "string"
    },
    "issuedAt": "2024-01-15T09:30:00Z",
    "expiresAt": "2024-01-15T09:30:00Z",
    "inLanguage": "string",
    "service": {
      "id": "https://example.com",
      "tenant": "https://example.com"
    },
    "recipient": "user@example.com",
    "subject": {
      "id": "https://example.com",
      "title": "string"
    },
    "terms": {
      "id": "https://example.com",
      "version": "string"
    },
    "details": {},
    "operations": [
      {
        "id": "string",
        "capability": {}
      }
    ],
    "human": {
      "url": "https://example.com"
    }
  },
  "idempotency_key": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "channel": "email",
  "to": "string",
  "cc": [
    "user@example.com"
  ],
  "bcc": [
    "user@example.com"
  ],
  "subject": "string",
  "body": "string",
  "html": "string",
  "template_id": 0,
  "contact_id": 0,
  "from": "string",
  "from_email": "string",
  "from_name": "string",
  "reply_to": "string",
  "headers": {},
  "tags": {},
  "data": {},
  "mail_action": {
    "@context": "https://mailschema.org/contexts/map-0.3.jsonld",
    "@type": "MailAction",
    "@id": "https://example.com",
    "profile": "https://mailschema.org/profiles/map/0.3",
    "type": {
      "id": "https://example.com",
      "version": "string",
      "contractDigest": "string"
    },
    "issuedAt": "2024-01-15T09:30:00Z",
    "expiresAt": "2024-01-15T09:30:00Z",
    "inLanguage": "string",
    "service": {
      "id": "https://example.com",
      "tenant": "https://example.com"
    },
    "recipient": "user@example.com",
    "subject": {
      "id": "https://example.com",
      "title": "string"
    },
    "terms": {
      "id": "https://example.com",
      "version": "string"
    },
    "details": {},
    "operations": [
      {
        "id": "string",
        "capability": {}
      }
    ],
    "human": {
      "url": "https://example.com"
    }
  },
  "idempotency_key": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/messages',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Sending log rows, filter counts and email engagement (Activity)

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `source_type` (query, string, optional) - Restrict to one source. Omit for every source.
  Type: string
  
  enum: ["campaign","flow","transactional","test"]

- `since` (query, string, optional) - Window by send time (creation time while unsent). Omit for all time.
  Type: string
  
  enum: ["today","7d","30d","3m"]

- `failed` (query, boolean, optional) - Only failed messages. Their rows report no engagement.
  Type: boolean

- `campaign_id` (query, integer, optional) - Only messages of this campaign's flows.
  Type: integer

- `limit` (query, integer, optional) - Maximum rows (1-100, default 50). Counts and engagement are not limited.
  Type: integer
  
  default: 50
  
  minimum: 1
  
  maximum: 100

Responses:

- 200: Sending log rows, filter counts and the Activity engagement.

Content type: application/json

Type: object

Schema: [MessageSendsResponse](https://docs.nitrosend.com/api/schemas/messagesendsresponse-88a9a1f9af.md)

- `rows` (required)
  Type: array
  
  Items:
    Reference: [MessageSendsRow](https://docs.nitrosend.com/api/schemas/messagesendsrow-d842990b20.md); Type: object

- `counts` (required)
  Reference: [MessageSendsCounts](https://docs.nitrosend.com/api/schemas/messagesendscounts-007f057fc0.md); Type: object
  
  Message counts for the filter pills, over the same window as the rows.

- `engagement` (required)
  Reference: [MessageSendsEngagement](https://docs.nitrosend.com/api/schemas/messagesendsengagement-5bdc200a80.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/messages/sends?limit=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/messages/sends?limit=50', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/messages/sends?limit=50',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get a transactional message

`GET /v1/my/messages/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Message

Content type: application/json

Type: object

Schema: [Message](https://docs.nitrosend.com/api/schemas/message-2f77668a9d.md)

- `id` (optional)
  Type: integer

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `to` (optional)
  Type: string

- `recipients` (optional)
  Type: object
  
  Full normalized email envelope, visible only to authorized account readers. Returned for email messages.
  
  - `to` (optional)
    Type: array
    
    Items:
      Type: string, email
  
  - `cc` (optional)
    Type: array
    
    Items:
      Type: string, email
  
  - `bcc` (optional)
    Type: array
    
    Items:
      Type: string, email

- `subject` (optional)
  Type: string; nullable

- `status` (optional)
  Type: string
  
  enum: ["queued","sent","failed"]

- `provider_id` (optional)
  Type: string; nullable

- `rfc_message_id` (optional)
  Type: string; nullable
  
  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_id` (optional)
  Type: integer; nullable
  
  Source flow ID (null for transactional)

- `source_type` (optional)
  Type: string; nullable
  
  campaign, flow, test, or null (transactional)
  
  enum: ["campaign","flow","test"]

- `source_name` (optional)
  Type: string; nullable
  
  Name of source campaign or flow

- `status_reason_code` (optional)
  Type: string; nullable
  
  Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

- `status_reason` (optional)
  Type: string; nullable
  
  Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

- `status_reason_category` (optional)
  Type: string; nullable
  
  Broad category for status_reason.
  
  enum: ["content_review","account","internal","recipient","provider","rate_limit","delivery"]

- `failure_code` (optional)
  Type: string; nullable
  
  Stable machine-readable failure reason; present only when status is failed.

- `failure_reason` (optional)
  Type: string; nullable
  
  Human-readable failure explanation; present only when status is failed.

- `failure_category` (optional)
  Type: string; nullable
  
  Broad category for failure_reason; present only when status is failed.
  
  enum: ["content_review","account","internal","recipient","provider","delivery"]

- `sent_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/messages/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/messages/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/messages/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Render a message subject and HTML for preview

`GET /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Rendered preview, or a typed empty state.

Content type: application/json

Type: object

- `subject` (optional)
  Type: string; nullable
  
  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.
  

- `html` (optional)
  Type: string; nullable
  
  Rendered HTML, or null when empty is true.

- `format` (optional)
  Type: string; nullable
  
  Composition source of the html, or null when empty.
  
  enum: ["template","raw","plain"]

- `empty` (optional)
  Type: boolean
  
  True when no HTML could be rendered (see reason).

- `reason` (optional)
  Type: string; nullable
  
  Why the preview is empty, when empty is true.
  
  enum: ["not_previewable","template_no_design","template_missing","template_render_error"]

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/messages/0/preview' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/messages/0/preview', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/messages/0/preview',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List suppressions

`GET /v1/my/suppressions`

Returns the authenticated account's current suppression records by
default, including bounded provider diagnostics when the source
feedback event is available.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (query, integer, optional) - Filter to a specific suppression ID
  Type: integer

- `email` (query, string, email, optional) - Filter to a specific suppressed email address
  Type: string, email

- `reason` (query, string, optional)
  Type: string
  
  enum: ["hard_bounce","soft_bounce","complaint","manual","admin","unsubscribe","verification","marketing_withheld","unconfirmed"]

- `source_provider` (query, string, optional) - Filter by provider that emitted the source event
  Type: string

- `active` (query, boolean, optional) - Defaults to true. Set false to list expired suppressions.
  Type: boolean
  
  default: true

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated list of suppressions

Content type: application/json

Type: array

Items:
  Reference: [Suppression](https://docs.nitrosend.com/api/schemas/suppression-858c847b74.md); Type: object
  
  Account suppression row with bounded source-event diagnostics.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/suppressions?active=true&page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/suppressions?active=true&page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/suppressions?active=true&page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List webhooks

`GET /v1/my/webhooks`

The current brand's webhook endpoints, oldest first, each with its newest delivery. Secrets are masked.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated list of webhooks

Content type: application/json

Type: array

Items:
  Reference: [Webhook](https://docs.nitrosend.com/api/schemas/webhook-4814f62c10.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/webhooks?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/webhooks?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/webhooks?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Register a webhook endpoint

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: unknown

allOf:
  Reference: [WebhookWriteRequest](https://docs.nitrosend.com/api/schemas/webhookwriterequest-8251acfea5.md); Type: object

  Type: unknown

Responses:

- 201: Webhook created, secret revealed

Content type: application/json

Type: object

Schema: [Webhook](https://docs.nitrosend.com/api/schemas/webhook-4814f62c10.md)

- `id` (optional)
  Type: integer

- `url` (optional)
  Type: string, uri

- `events` (optional)
  Type: array
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  `failing` while deliveries fail; an endpoint failing for 3 days is turned off.
  
  enum: ["active","failing","disabled"]

- `failing_since` (optional)
  Type: string, date-time; nullable

- `secret` (optional)
  Type: string
  
  Standard Webhooks signing secret (`whsec_...`). Masked unless revealed.

- `last_delivery` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `event_type` (optional)
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","delivered","failed"]
  
  - `attempts` (optional)
    Type: integer
  
  - `last_response_status` (optional)
    Type: integer; nullable
  
  - `updated_at` (optional)
    Type: string, date-time

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/webhooks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "enabled": true
}'
```

### JavaScript

```javascript
const body = `{
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "enabled": true
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "enabled": true
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/webhooks',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get a webhook

`GET /v1/my/webhooks/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `reveal` (query, boolean, optional) - Return the signing secret in full.
  Type: boolean
  
  default: false

Responses:

- 200: Webhook

Content type: application/json

Type: object

Schema: [Webhook](https://docs.nitrosend.com/api/schemas/webhook-4814f62c10.md)

- `id` (optional)
  Type: integer

- `url` (optional)
  Type: string, uri

- `events` (optional)
  Type: array
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  `failing` while deliveries fail; an endpoint failing for 3 days is turned off.
  
  enum: ["active","failing","disabled"]

- `failing_since` (optional)
  Type: string, date-time; nullable

- `secret` (optional)
  Type: string
  
  Standard Webhooks signing secret (`whsec_...`). Masked unless revealed.

- `last_delivery` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `event_type` (optional)
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","delivered","failed"]
  
  - `attempts` (optional)
    Type: integer
  
  - `last_response_status` (optional)
    Type: integer; nullable
  
  - `updated_at` (optional)
    Type: string, date-time

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/webhooks/0?reveal=false' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/webhooks/0?reveal=false', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/webhooks/0?reveal=false',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Delete a webhook and its delivery history

`DELETE /v1/my/webhooks/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Webhook deleted

Content type: application/json

Type: object

Schema: [Webhook](https://docs.nitrosend.com/api/schemas/webhook-4814f62c10.md)

- `id` (optional)
  Type: integer

- `url` (optional)
  Type: string, uri

- `events` (optional)
  Type: array
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  `failing` while deliveries fail; an endpoint failing for 3 days is turned off.
  
  enum: ["active","failing","disabled"]

- `failing_since` (optional)
  Type: string, date-time; nullable

- `secret` (optional)
  Type: string
  
  Standard Webhooks signing secret (`whsec_...`). Masked unless revealed.

- `last_delivery` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `event_type` (optional)
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","delivered","failed"]
  
  - `attempts` (optional)
    Type: integer
  
  - `last_response_status` (optional)
    Type: integer; nullable
  
  - `updated_at` (optional)
    Type: string, date-time

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X DELETE 'https://api.nitrosend.com/v1/my/webhooks/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/webhooks/0', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.delete(
    'https://api.nitrosend.com/v1/my/webhooks/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Update a webhook

`PATCH /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

Schema: [WebhookWriteRequest](https://docs.nitrosend.com/api/schemas/webhookwriterequest-8251acfea5.md)

- `url` (optional)
  Type: string, uri
  
  HTTPS URL that resolves only to public addresses, without credentials.
  
  maxLength: 2048

- `events` (optional)
  Type: array
  
  minItems: 1
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

Responses:

- 200: Webhook updated

Content type: application/json

Type: object

Schema: [Webhook](https://docs.nitrosend.com/api/schemas/webhook-4814f62c10.md)

- `id` (optional)
  Type: integer

- `url` (optional)
  Type: string, uri

- `events` (optional)
  Type: array
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  `failing` while deliveries fail; an endpoint failing for 3 days is turned off.
  
  enum: ["active","failing","disabled"]

- `failing_since` (optional)
  Type: string, date-time; nullable

- `secret` (optional)
  Type: string
  
  Standard Webhooks signing secret (`whsec_...`). Masked unless revealed.

- `last_delivery` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `event_type` (optional)
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","delivered","failed"]
  
  - `attempts` (optional)
    Type: integer
  
  - `last_response_status` (optional)
    Type: integer; nullable
  
  - `updated_at` (optional)
    Type: string, date-time

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/webhooks/0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "enabled": true
}'
```

### JavaScript

```javascript
const body = `{
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "enabled": true
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/webhooks/0', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "enabled": true
}'''

response = requests.patch(
    'https://api.nitrosend.com/v1/my/webhooks/0',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Send a test event

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json

Type: object

- `type` (optional)
  Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
  
  enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

Responses:

- 202: Test event queued

Content type: application/json

Type: object

Schema: [WebhookDelivery](https://docs.nitrosend.com/api/schemas/webhookdelivery-ff6158b877.md)

- `id` (optional)
  Type: integer

- `event_id` (optional)
  Type: string, uuid
  
  Sent as `webhook-id` (`evt_<event_id>`), stable across retries.

- `event_type` (optional)
  Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
  
  enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `status` (optional)
  Type: string
  
  enum: ["pending","delivered","failed"]

- `attempts` (optional)
  Type: integer

- `last_response_status` (optional)
  Type: integer; nullable

- `last_error` (optional)
  Type: string; nullable

- `next_attempt_at` (optional)
  Type: string, date-time

- `payload` (optional)
  Reference: [WebhookEventPayload](https://docs.nitrosend.com/api/schemas/webhookeventpayload-fe6402d1fd.md); Type: object

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Unknown event type, or the webhook is off

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/webhooks/0/test' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "type": "email.sent"
}'
```

### JavaScript

```javascript
const body = `{
  "type": "email.sent"
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/webhooks/0/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "type": "email.sent"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/webhooks/0/test',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List a webhook's deliveries

`GET /v1/my/webhooks/{id}/deliveries`

The last 7 days of deliveries to this webhook, newest first.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated list of deliveries

Content type: application/json

Type: array

Items:
  Reference: [WebhookDelivery](https://docs.nitrosend.com/api/schemas/webhookdelivery-ff6158b877.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/webhooks/0/deliveries?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/webhooks/0/deliveries?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/webhooks/0/deliveries?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## List persisted chat sessions

`GET /v1/my/chat_sessions`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated list of chat sessions

Content type: application/json

Type: array

Items:
  Reference: [ChatSession](https://docs.nitrosend.com/api/schemas/chatsession-fadcd47090.md); Type: object

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/chat_sessions?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/chat_sessions?page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/chat_sessions?page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get a persisted chat session with ordered messages

`GET /v1/my/chat_sessions/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Chat session

Content type: application/json

Type: ChatSessionDetail

Schema: [ChatSessionDetail](https://docs.nitrosend.com/api/schemas/chatsessiondetail-e50e5735ca.md)

allOf:
  Reference: [ChatSession](https://docs.nitrosend.com/api/schemas/chatsession-fadcd47090.md); Type: object

  Type: object
  
  - `messages` (optional)
    Type: array
    
    Items:
      Reference: [ChatMessage](https://docs.nitrosend.com/api/schemas/chatmessage-e51ae49d71.md); Type: object

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/chat_sessions/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/chat_sessions/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/chat_sessions/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Close an active persisted chat session

`PATCH /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Closed chat session

Content type: application/json

Type: object

Schema: [ChatSession](https://docs.nitrosend.com/api/schemas/chatsession-fadcd47090.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer

- `title` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["active","closed","failed"]

- `started_at` (optional)
  Type: string, date-time

- `last_message_at` (optional)
  Type: string, date-time

- `message_count` (optional)
  Type: integer

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X PATCH 'https://api.nitrosend.com/v1/my/chat_sessions/0/close' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/chat_sessions/0/close', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.patch(
    'https://api.nitrosend.com/v1/my/chat_sessions/0/close',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Create or exactly replay a resumable paid operation

`POST /v1/my/billing/paid_action_intents`

Persists encrypted, operation-owned continuation state. The intent is
not spend authority and never executes the operation automatically.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

Schema: [PaidActionIntentCreate](https://docs.nitrosend.com/api/schemas/paidactionintentcreate-9fd9478c78.md)

- `adapter_key` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 100

- `adapter_version` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 32

- `operation_idempotency_key` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 128

- `state_payload` (required)
  Type: object
  
  Adapter-owned state, validated and encrypted before persistence.
  
  Additional properties: true

Responses:

- 200: Exact idempotent replay

Content type: application/json

Type: object

Schema: [PaidActionIntent](https://docs.nitrosend.com/api/schemas/paidactionintent-d3b8ba9d30.md)

- `id` (required)
  Type: string
  
  Opaque public continuation identifier.
  
  minLength: 32
  
  maxLength: 64

- `schema` (required)
  Type: string
  
  const: "nitrosend.paid_action_intent.v1"

- `status` (required)
  Type: string
  
  enum: ["open","awaiting_funding","ready_to_resume","consumed","cancelled","expired"]

- `adapter` (required)
  Type: object
  
  - `key` (required)
    Type: string
  
  - `version` (required)
    Type: string

- `operation_idempotency_key` (required)
  Type: string

- `original_quote_fingerprint` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `current_quote_fingerprint` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `quote_changed` (optional)
  Type: boolean

- `state_payload` (optional)
  Type: object
  
  Additional properties: true

- `quote` (optional)
  Type: object
  
  Additional properties: true

- `expires_at` (required)
  Type: string, date-time

- `consumed_at` (optional)
  Type: string, date-time; nullable

- `cancelled_at` (optional)
  Type: string, date-time; nullable

- 201: Continuation created

Content type: application/json

Type: object

Schema: [PaidActionIntent](https://docs.nitrosend.com/api/schemas/paidactionintent-d3b8ba9d30.md)

- `id` (required)
  Type: string
  
  Opaque public continuation identifier.
  
  minLength: 32
  
  maxLength: 64

- `schema` (required)
  Type: string
  
  const: "nitrosend.paid_action_intent.v1"

- `status` (required)
  Type: string
  
  enum: ["open","awaiting_funding","ready_to_resume","consumed","cancelled","expired"]

- `adapter` (required)
  Type: object
  
  - `key` (required)
    Type: string
  
  - `version` (required)
    Type: string

- `operation_idempotency_key` (required)
  Type: string

- `original_quote_fingerprint` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `current_quote_fingerprint` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `quote_changed` (optional)
  Type: boolean

- `state_payload` (optional)
  Type: object
  
  Additional properties: true

- `quote` (optional)
  Type: object
  
  Additional properties: true

- `expires_at` (required)
  Type: string, date-time

- `consumed_at` (optional)
  Type: string, date-time; nullable

- `cancelled_at` (optional)
  Type: string, date-time; nullable

- 409: Operation key reused with different continuation state

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/billing/paid_action_intents' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "adapter_key": "string",
  "adapter_version": "string",
  "operation_idempotency_key": "string",
  "state_payload": {}
}'
```

### JavaScript

```javascript
const body = `{
  "adapter_key": "string",
  "adapter_version": "string",
  "operation_idempotency_key": "string",
  "state_payload": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/my/billing/paid_action_intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "adapter_key": "string",
  "adapter_version": "string",
  "operation_idempotency_key": "string",
  "state_payload": {}
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/my/billing/paid_action_intents',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Restore and re-quote a paid operation

`GET /v1/my/billing/paid_action_intents/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Opaque paid-operation continuation identifier.
  Type: string
  
  minLength: 32
  
  maxLength: 64

Responses:

- 200: Actor-scoped continuation with current terms

Content type: application/json

Type: object

Schema: [PaidActionIntent](https://docs.nitrosend.com/api/schemas/paidactionintent-d3b8ba9d30.md)

- `id` (required)
  Type: string
  
  Opaque public continuation identifier.
  
  minLength: 32
  
  maxLength: 64

- `schema` (required)
  Type: string
  
  const: "nitrosend.paid_action_intent.v1"

- `status` (required)
  Type: string
  
  enum: ["open","awaiting_funding","ready_to_resume","consumed","cancelled","expired"]

- `adapter` (required)
  Type: object
  
  - `key` (required)
    Type: string
  
  - `version` (required)
    Type: string

- `operation_idempotency_key` (required)
  Type: string

- `original_quote_fingerprint` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `current_quote_fingerprint` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `quote_changed` (optional)
  Type: boolean

- `state_payload` (optional)
  Type: object
  
  Additional properties: true

- `quote` (optional)
  Type: object
  
  Additional properties: true

- `expires_at` (required)
  Type: string, date-time

- `consumed_at` (optional)
  Type: string, date-time; nullable

- `cancelled_at` (optional)
  Type: string, date-time; nullable

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/my/billing/paid_action_intents/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/billing/paid_action_intents/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/my/billing/paid_action_intents/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Cancel and scrub a paid-operation continuation

`POST /v1/my/billing/paid_action_intents/{id}/cancel`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Opaque paid-operation continuation identifier.
  Type: string
  
  minLength: 32
  
  maxLength: 64

Responses:

- 200: Cancelled continuation

Content type: application/json

Type: object

Schema: [PaidActionIntent](https://docs.nitrosend.com/api/schemas/paidactionintent-d3b8ba9d30.md)

- `id` (required)
  Type: string
  
  Opaque public continuation identifier.
  
  minLength: 32
  
  maxLength: 64

- `schema` (required)
  Type: string
  
  const: "nitrosend.paid_action_intent.v1"

- `status` (required)
  Type: string
  
  enum: ["open","awaiting_funding","ready_to_resume","consumed","cancelled","expired"]

- `adapter` (required)
  Type: object
  
  - `key` (required)
    Type: string
  
  - `version` (required)
    Type: string

- `operation_idempotency_key` (required)
  Type: string

- `original_quote_fingerprint` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `current_quote_fingerprint` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `quote_changed` (optional)
  Type: boolean

- `state_payload` (optional)
  Type: object
  
  Additional properties: true

- `quote` (optional)
  Type: object
  
  Additional properties: true

- `expires_at` (required)
  Type: string, date-time

- `consumed_at` (optional)
  Type: string, date-time; nullable

- `cancelled_at` (optional)
  Type: string, date-time; nullable

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Terminal continuation cannot be cancelled

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/billing/paid_action_intents/string/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/billing/paid_action_intents/string/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/billing/paid_action_intents/string/cancel',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Mark a successfully executed paid operation consumed

`POST /v1/my/billing/paid_action_intents/{id}/consume`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, string, required) - Opaque paid-operation continuation identifier.
  Type: string
  
  minLength: 32
  
  maxLength: 64

Responses:

- 200: Consumed continuation

Content type: application/json

Type: object

Schema: [PaidActionIntent](https://docs.nitrosend.com/api/schemas/paidactionintent-d3b8ba9d30.md)

- `id` (required)
  Type: string
  
  Opaque public continuation identifier.
  
  minLength: 32
  
  maxLength: 64

- `schema` (required)
  Type: string
  
  const: "nitrosend.paid_action_intent.v1"

- `status` (required)
  Type: string
  
  enum: ["open","awaiting_funding","ready_to_resume","consumed","cancelled","expired"]

- `adapter` (required)
  Type: object
  
  - `key` (required)
    Type: string
  
  - `version` (required)
    Type: string

- `operation_idempotency_key` (required)
  Type: string

- `original_quote_fingerprint` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `current_quote_fingerprint` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `quote_changed` (optional)
  Type: boolean

- `state_payload` (optional)
  Type: object
  
  Additional properties: true

- `quote` (optional)
  Type: object
  
  Additional properties: true

- `expires_at` (required)
  Type: string, date-time

- `consumed_at` (optional)
  Type: string, date-time; nullable

- `cancelled_at` (optional)
  Type: string, date-time; nullable

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: Continuation is not ready to consume

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/my/billing/paid_action_intents/string/consume' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/my/billing/paid_action_intents/string/consume', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/my/billing/paid_action_intents/string/consume',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Read an anonymous flow demo

`GET /v1/public/flow_demo`

A demo past its scan deadline (3 minutes) or its generation deadline
(8 minutes) reads as failed.


Authentication: no security requirement declared for this operation.

Parameters:

- `X-Flow-Demo-Token` (header, string, required)
  Type: string

Responses:

- 200: Current demo state

Content type: application/json

Type: 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.


Schema: [GuestFlowDemo](https://docs.nitrosend.com/api/schemas/guestflowdemo-b13d0caa22.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","generating","ready","failed","expired"]

- `revision` (optional)
  Type: integer
  
  Advances with each brand edit or generation retry. Absent when expired.

- `domain` (optional)
  Type: string

- `goal` (optional)
  Type: string

- `brand` (optional)
  Type: object
  
  Scanned Brand Kit fields, present once the scan has completed.
  
  Additional properties: true

- `logo_url` (optional)
  Type: string
  
  Scanned logo

- `flow` (optional)
  Type: object
  
  The generated draft for the current revision, present when ready.
  
  Additional properties: true

- `failed_stage` (optional)
  Type: string
  
  Present when failed. A failed scan cannot be retried; start again.
  
  enum: ["scan","generate"]

- `message` (optional)
  Type: string
  
  Visitor copy, present when failed or expired.

- `error_code` (optional)
  Type: string
  
  Present when a generation failed on the demo's last attempt: it cannot be retried, and `message` offers an account instead.
  
  enum: ["flow_demo_attempts_exhausted"]

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/public/flow_demo' \
  -H 'X-Flow-Demo-Token: string'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/public/flow_demo', {
  method: 'GET',
  headers: {
    'X-Flow-Demo-Token': 'string',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/public/flow_demo',
    headers={
        'X-Flow-Demo-Token': 'string',
    },
)
print(response.text)
```


## Start an anonymous brand scan for a flow demo

`POST /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.


Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `domain` (required)
  Type: string
  
  maxLength: 253

- `goal` (required)
  Type: string
  
  maxLength: 1000

- `turnstile_token` (required)
  Type: string
  
  Single-use Turnstile token for the flow_demo_start action

Responses:

- 202: Scan started

Content type: application/json

Type: object

- `token` (required)
  Type: string
  
  Opaque bearer token kept on the visitor's device

- `status` (required)
  Type: string
  
  enum: ["scanning"]

- `revision` (required)
  Type: integer

- 422: Invalid or private website or goal (`flow_demo_invalid`), or a
missing or failed bot check (`flow_demo_bot_check_failed`).


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 429: Per-IP demo start limit reached

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 503: The demo is unavailable or its daily cap is spent
(`flow_demo_unavailable`).


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/public/flow_demo' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "domain": "string",
  "goal": "string",
  "turnstile_token": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "domain": "string",
  "goal": "string",
  "turnstile_token": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/public/flow_demo', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "domain": "string",
  "goal": "string",
  "turnstile_token": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/public/flow_demo',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Edit the scanned Brand Kit and regenerate the flow

`POST /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.


Authentication: no security requirement declared for this operation.

Parameters:

- `X-Flow-Demo-Token` (header, string, required)
  Type: string

Request body: application/json (required)

Type: object

- `fields` (required)
  Type: object
  
  Additional properties: true

Responses:

- 200: The demo after the edit

Content type: application/json

Type: 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.


Schema: [GuestFlowDemo](https://docs.nitrosend.com/api/schemas/guestflowdemo-b13d0caa22.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","generating","ready","failed","expired"]

- `revision` (optional)
  Type: integer
  
  Advances with each brand edit or generation retry. Absent when expired.

- `domain` (optional)
  Type: string

- `goal` (optional)
  Type: string

- `brand` (optional)
  Type: object
  
  Scanned Brand Kit fields, present once the scan has completed.
  
  Additional properties: true

- `logo_url` (optional)
  Type: string
  
  Scanned logo

- `flow` (optional)
  Type: object
  
  The generated draft for the current revision, present when ready.
  
  Additional properties: true

- `failed_stage` (optional)
  Type: string
  
  Present when failed. A failed scan cannot be retried; start again.
  
  enum: ["scan","generate"]

- `message` (optional)
  Type: string
  
  Visitor copy, present when failed or expired.

- `error_code` (optional)
  Type: string
  
  Present when a generation failed on the demo's last attempt: it cannot be retried, and `message` offers an account instead.
  
  enum: ["flow_demo_attempts_exhausted"]

- 422: Expired or unscanned demo, or a field that is not an editable brand
field (`flow_demo_invalid`); no attempts left
(`flow_demo_attempts_exhausted`).


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/public/flow_demo/review' \
  -H 'X-Flow-Demo-Token: string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "fields": {}
}'
```

### JavaScript

```javascript
const body = `{
  "fields": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/public/flow_demo/review', {
  method: 'POST',
  headers: {
    'X-Flow-Demo-Token': 'string',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "fields": {}
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/public/flow_demo/review',
    data=body.encode('utf-8'),
    headers={
        'X-Flow-Demo-Token': 'string',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Retry a demo that failed during generation

`POST /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.


Authentication: no security requirement declared for this operation.

Parameters:

- `X-Flow-Demo-Token` (header, string, required)
  Type: string

Responses:

- 200: The demo after the retry

Content type: application/json

Type: 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.


Schema: [GuestFlowDemo](https://docs.nitrosend.com/api/schemas/guestflowdemo-b13d0caa22.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","generating","ready","failed","expired"]

- `revision` (optional)
  Type: integer
  
  Advances with each brand edit or generation retry. Absent when expired.

- `domain` (optional)
  Type: string

- `goal` (optional)
  Type: string

- `brand` (optional)
  Type: object
  
  Scanned Brand Kit fields, present once the scan has completed.
  
  Additional properties: true

- `logo_url` (optional)
  Type: string
  
  Scanned logo

- `flow` (optional)
  Type: object
  
  The generated draft for the current revision, present when ready.
  
  Additional properties: true

- `failed_stage` (optional)
  Type: string
  
  Present when failed. A failed scan cannot be retried; start again.
  
  enum: ["scan","generate"]

- `message` (optional)
  Type: string
  
  Visitor copy, present when failed or expired.

- `error_code` (optional)
  Type: string
  
  Present when a generation failed on the demo's last attempt: it cannot be retried, and `message` offers an account instead.
  
  enum: ["flow_demo_attempts_exhausted"]

- 422: Expired demo or a failed scan (`flow_demo_invalid`); no attempts
left (`flow_demo_attempts_exhausted`).


Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/public/flow_demo/generate' \
  -H 'X-Flow-Demo-Token: string'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/public/flow_demo/generate', {
  method: 'POST',
  headers: {
    'X-Flow-Demo-Token': 'string',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.post(
    'https://api.nitrosend.com/v1/public/flow_demo/generate',
    headers={
        'X-Flow-Demo-Token': 'string',
    },
)
print(response.text)
```


## Get guest-safe Flow Builder steps and triggers

`GET /v1/public/flow_demo/spec`

Authentication: no security requirement declared for this operation.

Responses:

- 200: Flow editor schema restricted to guest-authorable actions

Content type: application/json

Type: object

Additional properties: true

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/public/flow_demo/spec'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/public/flow_demo/spec', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/v1/public/flow_demo/spec')
print(response.text)
```


## Get a canonical email template for guest editing

`GET /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.


Authentication: no security requirement declared for this operation.

Parameters:

- `id` (path, string, required)
  Type: string

- `revision` (query, string, optional) - Open only the design revision shown in a published gallery preview.
  Type: string
  
  pattern: "^[a-f0-9]{64}$"

Responses:

- 200: Canonical catalog template

Content type: application/json

Type: object

Schema: [PublicEmailCatalogTemplate](https://docs.nitrosend.com/api/schemas/publicemailcatalogtemplate-4a9b6b54b1.md)

- `id` (required)
  Type: string

- `revision` (optional)
  Type: string
  
  Digest of the concrete public design.
  
  pattern: "^[a-f0-9]{64}$"

- `collection` (optional)
  Type: string
  
  Present for a brand concept study; originals retain their existing response shape.
  
  enum: ["brand_studies"]

- `study` (optional)
  Type: object
  
  - `brand` (required)
    Type: string
  
  - `concept` (required)
    Type: boolean
    
    enum: [true]
  
  - `adapted` (optional)
    Type: boolean
  
  - `source_url` (required)
    Type: string, uri
  
  Additional properties: false

- `name` (required)
  Type: string

- `category` (required)
  Type: string

- `tags` (required)
  Type: array
  
  Items:
    Type: string

- `description` (required)
  Type: string

- `subject` (required)
  Type: string

- `preheader` (required)
  Type: string

- `design` (required)
  Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
  
  Email template design document

Additional properties: false

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 409: The requested preview revision is no longer current. The visitor can explicitly open the current version.

Content type: application/json

Type: object

Additional properties: true

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/public/templates/string'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/public/templates/string', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/v1/public/templates/string')
print(response.text)
```


## Get the email editor schema for guest editing

`GET /v1/public/templates/spec`

Returns the canonical component and theme schema used by the email editor.

Authentication: no security requirement declared for this operation.

Responses:

- 200: Email component schema

Content type: application/json

Type: object

Full schema for email design sections. Each component has type,
description, props (with types, required flags, defaults), and tips.


Schema: [EmailComponentSpec](https://docs.nitrosend.com/api/schemas/emailcomponentspec-39b992201d.md)

- `version` (required)
  Type: integer

- `design_guidelines` (required)
  Type: string

- `renderer_version` (required)
  Type: string
  
  The @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.

- `components` (required)
  Type: array
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
    
    - `description` (required)
      Type: string
    
    - `tips` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `props` (required)
      Type: object
      
      Additional properties: 
        Type: object
        
        - `type` (required)
          Type: string
        
        - `required` (optional)
          Type: boolean
        
        - `default` (optional)
          Type: unknown
        
        - `description` (optional)
          Type: string
        
        - `enum` (optional)
          Type: array
          
          Items:
            Type: string
        
        - `items` (optional)
          Type: object
          
          Additional properties: 
            Type: object
            
            - `type` (required)
              Type: string
            
            - `description` (required)
              Type: string
            
            Additional properties: false
        
        - `server_owned` (optional)
          Type: boolean
        
        - `unset_when_empty` (optional)
          Type: boolean
          
          An empty value is allowed in a draft; delivery leaves the section out.
        
        - `theme_key` (optional)
          Type: string
        
        Additional properties: false
    
    Additional properties: false

- `style_attributes` (required)
  Type: array
  
  Standard per-section style attribute registry.
  
  Items:
    Type: object
    
    - `key` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["color","spacing","enum","number","boolean"]
    
    - `applies_to` (required)
      Type: unknown
    
    - `default` (optional)
      Type: unknown
    
    - `theme_fallback` (optional)
      Type: string
    
    - `description` (required)
      Type: string
    
    - `min` (optional)
      Type: integer
    
    - `max` (optional)
      Type: integer
    
    - `values` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `target` (required)
      Type: object
      
      - `el` (required)
        Type: string
        
        enum: ["section","content","shape"]
      
      - `attr` (optional)
        Type: string
      
      Additional properties: false
    
    Additional properties: false

- `preview_document` (required)
  Type: object
  
  - `parameter` (required)
    Type: string
  
  - `description` (required)
    Type: string
  
  - `example` (required)
    Type: object
    
    Additional properties: true
  
  Additional properties: false

- `variables` (required)
  Type: object
  
  Merge variables grouped by source namespace.
  
  Additional properties: 
    Type: array
    
    Items:
      Type: object
      
      - `name` (required)
        Type: string
      
      - `description` (required)
        Type: string
      
      Additional properties: false

- `filters` (required)
  Type: array
  
  Items:
    Type: object
    
    - `name` (required)
      Type: string
    
    - `syntax` (required)
      Type: string
    
    - `description` (required)
      Type: string
    
    Additional properties: false

- `theme_attributes` (required)
  Type: array
  
  Brand Kit theme attribute registry (single source of truth for the editor).
  
  Items:
    Type: object
    
    - `key` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["color","font","number","enum","spacing","string","image","array"]
    
    - `default` (optional)
      Type: unknown
    
    - `category` (required)
      Type: string
      
      enum: ["color","font","visual_identity","identity"]
    
    - `slot` (optional)
      Type: string
    
    - `surfaces` (required)
      Type: array
      
      Items:
        Type: string
    
    - `min` (optional)
      Type: integer
    
    - `max` (optional)
      Type: integer
    
    - `values` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `options` (optional)
      Type: array
      
      Items:
        Type: object
        
        - `value` (optional)
          Type: string
        
        - `label` (optional)
          Type: string
        
        - `description` (optional)
          Type: string
    
    - `transform_table` (optional)
      Type: object
      
      Additional properties: 
        Type: string
    
    - `column` (optional)
      Type: boolean
    
    - `storage` (optional)
      Type: string
    
    - `placeholder` (optional)
      Type: string
    
    - `value_resolver` (optional)
      Type: string
    
    - `server_owned` (optional)
      Type: boolean
    
    - `description` (optional)
      Type: string
    
    Additional properties: false

Additional properties: false

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/public/templates/spec'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/public/templates/spec', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/v1/public/templates/spec')
print(response.text)
```


## Create or update a public contact (website forms)

`POST /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.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `email` (required)
  Type: string, email
  
  Subscriber email address.

- `list_id` (required)
  Type: integer
  
  ID of a contact list owned by the brand whose public key is presented.

- `first_name` (optional)
  Type: string; nullable
  
  Optional first name written to the contact.

- `last_name` (optional)
  Type: string; nullable
  
  Optional last name written to the contact.

- `phone` (optional)
  Type: string; nullable
  
  Optional E.164 phone number written to the SMS channel if provided.

- `source` (optional)
  Type: string; nullable
  
  Optional free-text label, e.g. "footer-form" or "/pricing", recorded against the signup.

- `data` (optional)
  Type: object; nullable
  
  Optional bag of custom contact data. Reserved keys are silently dropped.
  
  Additional properties: true

Responses:

- 201: Contact accepted

Content type: application/json

Type: object

- `ok` (required)
  Type: boolean
  
  const: true

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

- 429: Rate limit exceeded

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/public/contacts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "list_id": 0,
  "first_name": "string",
  "last_name": "string",
  "phone": "string",
  "source": "string",
  "data": {}
}'
```

### JavaScript

```javascript
const body = `{
  "email": "user@example.com",
  "list_id": 0,
  "first_name": "string",
  "last_name": "string",
  "phone": "string",
  "source": "string",
  "data": {}
}`;

const response = await fetch('https://api.nitrosend.com/v1/public/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "email": "user@example.com",
  "list_id": 0,
  "first_name": "string",
  "last_name": "string",
  "phone": "string",
  "source": "string",
  "data": {}
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/public/contacts',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Get available plans

`GET /v1/app`

Authentication: no security requirement declared for this operation.

Responses:

- 200: Active plans

Content type: application/json

Type: object

- `plans` (optional)
  Type: array
  
  Items:
    Reference: [Plan](https://docs.nitrosend.com/api/schemas/plan-fa8ed0bdab.md); Type: object

- `stripe_publishable_key` (optional)
  Type: string; nullable

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/app'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/app', {
  method: 'GET',
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get('https://api.nitrosend.com/v1/app')
print(response.text)
```


## Make an existing account a partner

`POST /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`.


Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Request body: application/json (required)

Type: object

- `account_id` (optional)
  Type: integer

- `user_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

Responses:

- 200: Partner access enabled, or already enabled

Content type: application/json

Type: object

Schema: [StaffPartnerGrantResult](https://docs.nitrosend.com/api/schemas/staffpartnergrantresult-3e1386b426.md)

- `status` (required)
  Type: string
  
  enum: ["partner_enabled","already_partner"]

- `message` (required)
  Type: string

- `account_id` (required)
  Type: integer

- `email` (optional)
  Type: string; nullable

- `plan` (optional)
  Type: string; nullable
  
  The account's current plan slug, unchanged by this call.

- `commercial_tier` (optional)
  Type: string; nullable

- `capabilities` (required)
  Type: array
  
  Items:
    Type: string
    
    enum: ["affiliate_center","managed_clients"]

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Partner access was revoked by an admin and is not re-granted

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/staff/comps' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "account_id": 0,
  "user_id": 0,
  "email": "user@example.com"
}'
```

### JavaScript

```javascript
const body = `{
  "account_id": 0,
  "user_id": 0,
  "email": "user@example.com"
}`;

const response = await fetch('https://api.nitrosend.com/v1/staff/comps', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "account_id": 0,
  "user_id": 0,
  "email": "user@example.com"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/staff/comps',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## List the production customer-support queue

`GET /v1/operator/support_requests`

Requires an `nskey_live_...` API key owned by an admin or staff user. Browser JWTs are rejected.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `status` (query, string, optional)
  Type: string
  
  Comma-separated open

- `due_only` (query, boolean, optional)
  Type: boolean
  
  default: false

- `account_id` (query, integer, optional)
  Type: integer

- `brand_id` (query, integer, optional)
  Type: integer

- `page` (query, integer, optional)
  Type: integer
  
  default: 1

- `limit` (query, integer, optional)
  Type: integer
  
  default: 25
  
  maximum: 100

Responses:

- 200: Paginated support queue

Content type: application/json

Type: array

Items:
  Reference: [OperatorSupportRequest](https://docs.nitrosend.com/api/schemas/operatorsupportrequest-a7324b17cb.md); Type: object

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/operator/support_requests?due_only=false&page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/operator/support_requests?due_only=false&page=1&limit=25', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/operator/support_requests?due_only=false&page=1&limit=25',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Get one production support case

`GET /v1/operator/support_requests/{id}`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Support request, customer account, brand, and latest reply ledger state

Content type: application/json

Type: object

Schema: [OperatorSupportCase](https://docs.nitrosend.com/api/schemas/operatorsupportcase-2683ecb58a.md)

- `support_request` (required)
  Type: unknown
  
  allOf:
    Reference: [OperatorSupportRequest](https://docs.nitrosend.com/api/schemas/operatorsupportrequest-a7324b17cb.md); Type: object
  
    Type: object
    
    - `support_transcript` (optional)
      Type: string; nullable
    
    - `support_transcript_truncated` (optional)
      Type: boolean

- `account` (required)
  Type: object
  
  Additional properties: true

- `brand` (required)
  Type: object
  
  Additional properties: true

- `latest_reply` (optional)
  Type: object; nullable
  
  Additional properties: true

- `github_issue` (optional)
  Type: object; nullable
  
  Additional properties: true

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/operator/support_requests/0' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/operator/support_requests/0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/operator/support_requests/0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Read bounded live diagnostics for a support case

`GET /v1/operator/support_requests/{id}/diagnostics`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Responses:

- 200: Current sending, DNS, campaign, and message evidence

Content type: application/json

Type: object

Additional properties: true

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X GET 'https://api.nitrosend.com/v1/operator/support_requests/0/diagnostics' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://api.nitrosend.com/v1/operator/support_requests/0/diagnostics', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://api.nitrosend.com/v1/operator/support_requests/0/diagnostics',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```


## Persist a versioned customer reply draft

`POST /v1/operator/support_requests/{id}/draft`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `body` (required)
  Type: string

- `runx_receipt_id` (optional)
  Type: string; nullable

Responses:

- 201: Draft persisted in the reply ledger

Content type: application/json

Type: object

Schema: [OperatorReplyDraft](https://docs.nitrosend.com/api/schemas/operatorreplydraft-04791a462c.md)

- `status` (required)
  Type: string
  
  enum: ["drafted","sent"]

- `support_request_id` (required)
  Type: integer

- `thread_record_id` (required)
  Type: integer

- `draft_version` (required)
  Type: integer

- `draft_state` (optional)
  Type: string

- `terminal_outcome` (optional)
  Type: string; nullable

- `last_replied_at` (optional)
  Type: string, date-time; nullable

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/operator/support_requests/0/draft' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "body": "string",
  "runx_receipt_id": "string"
}'
```

### JavaScript

```javascript
const body = `{
  "body": "string",
  "runx_receipt_id": "string"
}`;

const response = await fetch('https://api.nitrosend.com/v1/operator/support_requests/0/draft', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "body": "string",
  "runx_receipt_id": "string"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/operator/support_requests/0/draft',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Send one current versioned customer reply

`POST /v1/operator/support_requests/{id}/send_reply`

Delivery is fail-closed and requires `confirm: true`; stale draft versions are rejected by the server ledger.

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `thread_record_id` (required)
  Type: integer

- `draft_version` (required)
  Type: integer

- `confirm` (required)
  Type: boolean
  
  const: true

Responses:

- 200: Reply delivered

Content type: application/json

Type: object

Schema: [OperatorReplyDraft](https://docs.nitrosend.com/api/schemas/operatorreplydraft-04791a462c.md)

- `status` (required)
  Type: string
  
  enum: ["drafted","sent"]

- `support_request_id` (required)
  Type: integer

- `thread_record_id` (required)
  Type: integer

- `draft_version` (required)
  Type: integer

- `draft_state` (optional)
  Type: string

- `terminal_outcome` (optional)
  Type: string; nullable

- `last_replied_at` (optional)
  Type: string, date-time; nullable

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 422: Validation failed

Content type: application/json

Type: unknown

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `validation_errors` (optional)
    Type: object
    
    Additional properties: 
      Type: array
      
      Items:
        Type: string

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/operator/support_requests/0/send_reply' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "thread_record_id": 0,
  "draft_version": 0,
  "confirm": true
}'
```

### JavaScript

```javascript
const body = `{
  "thread_record_id": 0,
  "draft_version": 0,
  "confirm": true
}`;

const response = await fetch('https://api.nitrosend.com/v1/operator/support_requests/0/send_reply', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "thread_record_id": 0,
  "draft_version": 0,
  "confirm": true
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/operator/support_requests/0/send_reply',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## Set the persistent support-case disposition

`POST /v1/operator/support_requests/{id}/disposition`

Authentication (security requirement alternatives):

```json
[
  {
    "BearerAuth": []
  }
]
```

- BearerAuth: http (bearer). Authentication scheme depends on the route:

- Authenticated endpoints (`/v1/my/*`) accept a server API key
  (`nskey_live_...`), a Nitrosend JWT, or a verified Shopify App Bridge
  ID token for an active embedded installation. API key is checked first.
- Public website-form endpoints (`/v1/public/*`) require a brand
  public key (`wpkey_live_...`). Secret keys (`nskey_live_...`)
  are rejected here so they can't be smuggled into browser code.

For accounts with multiple brands, include the `X-Brand-SID` header to scope
requests to a specific brand. If omitted, the account's default
brand is used. JWT requests can also include `X-Account-ID` to select
an accessible account.


Parameters:

- `id` (path, integer, required)
  Type: integer

Request body: application/json (required)

Type: object

- `status` (required)
  Type: string
  
  enum: ["open","waiting","resolved"]

- `confirm` (required)
  Type: boolean
  
  Explicit confirmation of the disposition mutation.
  
  enum: [true]

- `follow_up_at` (optional)
  Type: string, date-time
  
  Required only for waiting.

Responses:

- 200: Updated support request

Content type: application/json

Type: object

Schema: [OperatorSupportRequest](https://docs.nitrosend.com/api/schemas/operatorsupportrequest-a7324b17cb.md)

- `id` (required)
  Type: integer

- `account_id` (required)
  Type: integer

- `brand_id` (required)
  Type: integer

- `subject` (required)
  Type: string

- `message` (required)
  Type: string

- `status` (required)
  Type: string
  
  enum: ["open","waiting","resolved"]

- `follow_up_at` (optional)
  Type: string, date-time; nullable

- `resolved_at` (optional)
  Type: string, date-time; nullable

- `last_replied_at` (optional)
  Type: string, date-time; nullable

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

- 400: Bad request

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 401: Not authenticated

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 403: Not authorized

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

- 404: Resource not found

Content type: application/json

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## Examples

### cURL

```bash
curl -X POST 'https://api.nitrosend.com/v1/operator/support_requests/0/disposition' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "status": "open",
  "confirm": true,
  "follow_up_at": "2024-01-15T09:30:00Z"
}'
```

### JavaScript

```javascript
const body = `{
  "status": "open",
  "confirm": true,
  "follow_up_at": "2024-01-15T09:30:00Z"
}`;

const response = await fetch('https://api.nitrosend.com/v1/operator/support_requests/0/disposition', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();
```

### Python

```python
import requests

body = '''{
  "status": "open",
  "confirm": true,
  "follow_up_at": "2024-01-15T09:30:00Z"
}'''

response = requests.post(
    'https://api.nitrosend.com/v1/operator/support_requests/0/disposition',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)
```


## WorkspaceRoute

Type: object

Schema: [WorkspaceRoute](https://docs.nitrosend.com/api/schemas/workspaceroute-7da4aded72.md)

- `name` (required)
  Type: string

- `params` (optional)
  Type: object
  
  Additional properties: true

- `query` (optional)
  Type: object
  
  Additional properties: true

## WorkspaceAttentionItem

Type: object

Schema: [WorkspaceAttentionItem](https://docs.nitrosend.com/api/schemas/workspaceattentionitem-01416e6e3e.md)

- `key` (required)
  Type: string

- `title` (required)
  Type: string

- `detail` (required)
  Type: string

- `state` (required)
  Type: string
  
  enum: ["action_required","working"]

- `blocking` (required)
  Type: boolean

- `updated_at` (required)
  Type: string, date-time

- `to` (required)
  Type: unknown
  
  oneOf:
    Reference: [WorkspaceRoute](https://docs.nitrosend.com/api/schemas/workspaceroute-7da4aded72.md); Type: object
  
    Type: null

- `action` (required)
  Type: string

- `href` (optional)
  Type: string

- `progress` (optional)
  Type: object
  
  Additional properties: true

- `dismissible` (optional)
  Type: boolean

- `chat_session_id` (optional)
  Type: integer

- `priority` (optional)
  Type: integer
  
  Account-wide restrictions use 0 and precede individual tasks.

- `recovery_actions` (optional)
  Type: array
  
  Existing recovery actions for this restriction; opening one never approves or resumes sending.
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `url` (required)
      Type: string

## WorkspaceActivityItem

Type: object

Schema: [WorkspaceActivityItem](https://docs.nitrosend.com/api/schemas/workspaceactivityitem-fae1c02ca7.md)

- `id` (required)
  Type: integer

- `source` (required)
  Type: string
  
  enum: ["mcp","nitrollm","api"]

- `title` (required)
  Type: string

- `outcome` (required)
  Type: string
  
  enum: ["ok","incomplete","accepted","streamed","denied","error","http_error","unknown"]

- `client` (required)
  Type: string; nullable

- `created_at` (required)
  Type: string, date-time

- `to` (required)
  Type: unknown
  
  oneOf:
    Reference: [WorkspaceRoute](https://docs.nitrosend.com/api/schemas/workspaceroute-7da4aded72.md); Type: object
  
    Type: null

## OperatorSupportRequest

Type: object

Schema: [OperatorSupportRequest](https://docs.nitrosend.com/api/schemas/operatorsupportrequest-a7324b17cb.md)

- `id` (required)
  Type: integer

- `account_id` (required)
  Type: integer

- `brand_id` (required)
  Type: integer

- `subject` (required)
  Type: string

- `message` (required)
  Type: string

- `status` (required)
  Type: string
  
  enum: ["open","waiting","resolved"]

- `follow_up_at` (optional)
  Type: string, date-time; nullable

- `resolved_at` (optional)
  Type: string, date-time; nullable

- `last_replied_at` (optional)
  Type: string, date-time; nullable

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

## OperatorSupportCase

Type: object

Schema: [OperatorSupportCase](https://docs.nitrosend.com/api/schemas/operatorsupportcase-2683ecb58a.md)

- `support_request` (required)
  Type: unknown
  
  allOf:
    Reference: [OperatorSupportRequest](https://docs.nitrosend.com/api/schemas/operatorsupportrequest-a7324b17cb.md); Type: object
  
    Type: object
    
    - `support_transcript` (optional)
      Type: string; nullable
    
    - `support_transcript_truncated` (optional)
      Type: boolean

- `account` (required)
  Type: object
  
  Additional properties: true

- `brand` (required)
  Type: object
  
  Additional properties: true

- `latest_reply` (optional)
  Type: object; nullable
  
  Additional properties: true

- `github_issue` (optional)
  Type: object; nullable
  
  Additional properties: true

## OperatorReplyDraft

Type: object

Schema: [OperatorReplyDraft](https://docs.nitrosend.com/api/schemas/operatorreplydraft-04791a462c.md)

- `status` (required)
  Type: string
  
  enum: ["drafted","sent"]

- `support_request_id` (required)
  Type: integer

- `thread_record_id` (required)
  Type: integer

- `draft_version` (required)
  Type: integer

- `draft_state` (optional)
  Type: string

- `terminal_outcome` (optional)
  Type: string; nullable

- `last_replied_at` (optional)
  Type: string, date-time; nullable

## TimelineEntry

Type: object

One normalised, whitelisted entry in a contact's unified timeline.

Schema: [TimelineEntry](https://docs.nitrosend.com/api/schemas/timelineentry-94a0220211.md)

- `id` (required)
  Type: string
  
  Stable composite id, e.g. "event-123".

- `kind` (required)
  Type: string
  
  enum: ["event","activity","lifecycle","message"]

- `type` (required)
  Type: string
  
  Event/activity/lifecycle type, e.g. checkout, opened, flow_exit.

- `title` (required)
  Type: string
  
  Human-readable label for the entry.

- `occurred_at` (required)
  Type: string, date-time

- `meta` (required)
  Type: object
  
  Display-only extras (e.g. amount, resource_name). Flow exits include the flow name in resource_name and its exit_event. No internal fields.
  
  Additional properties: true

## EnterpriseRequestInput

Type: object

Schema: [EnterpriseRequestInput](https://docs.nitrosend.com/api/schemas/enterpriserequestinput-bf27cf7003.md)

- `monthly_emails` (optional)
  Type: unknown
  
  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.
  
  oneOf:
    Type: integer
    
    minimum: 0
    
    maximum: 1000000000
  
    Type: string
    
    pattern: "^[0-9]{1,10}$"
  
    Type: null

- `needs` (optional)
  Type: array; nullable
  
  maxItems: 6
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["volume_pricing","dedicated_ip","seats_or_domains","security_review","invoicing","migration"]

- `message` (optional)
  Type: string; nullable
  
  maxLength: 2000

Additional properties: false

## EnterpriseRequestReceipt

Type: object

Schema: [EnterpriseRequestReceipt](https://docs.nitrosend.com/api/schemas/enterpriserequestreceipt-586909efa0.md)

- `received` (required)
  Type: boolean
  
  const: true

- `replayed` (required)
  Type: boolean
  
  True when this is the member's request from earlier today.

- `request` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `received_at` (required)
    Type: string, date-time
  
  - `requester_email` (required)
    Type: string, email
    
    Where the team will reply.

## SafetyRecoveryAction

Type: object

Schema: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md)

- `type` (required)
  Type: string
  
  enum: ["ask_team","domain_settings"]

- `label` (required)
  Type: string

- `url` (required)
  Type: string
  
  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_id` (optional)
  Type: integer
  
  The held case

- `prompt` (optional)
  Type: string
  
  The staged request

## SendRefusalDetail

Type: 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).


Schema: [SendRefusalDetail](https://docs.nitrosend.com/api/schemas/sendrefusaldetail-6a89f2dddc.md)

- `reason_code` (optional)
  Type: string
  
  enum: ["content.image_unavailable","content.unreviewable","content.vetting_review","content.vetting_denied"]

- `how_to_fix` (optional)
  Type: string
  
  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.
  

- `category` (optional)
  Type: string
  
  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_prompt` (optional)
  Type: string
  
  The reason and fix as one paragraph to paste to an agent. Names IDs only, never text from the email.

- `recovery_actions` (optional)
  Type: array
  
  Items:
    Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object

- `details` (optional)
  Type: object
  
  - `images` (optional)
    Type: array
    
    Each image that couldn't be loaded.
    
    Items:
      Type: object
      
      - `url` (optional)
        Type: string
        
        The image address
      
      - `problem` (optional)
        Type: string
        
        enum: ["not_found","refused","rejected","server_error","unreachable","private_host","unsupported_type","too_large","too_many_pixels","unreadable","not_a_web_address","unsupported_inline_image"]
      
      - `http_status` (optional)
        Type: integer
        
        The image host's HTTP status
  
  - `changes` (optional)
    Type: array
    
    Other changes the email needs before it can be checked.
    
    Items:
      Type: object
      
      - `code` (optional)
        Type: string
      
      - `fix` (optional)
        Type: string
  
  - `review_id` (optional)
    Type: integer
    
    The held or blocked case, for a request to the team.
  
  - `model_reason` (optional)
    Type: string
    
    The safety check's own reason, for trusted accounts only.

## Error

Type: object

Schema: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `recovery_action` (optional)
  Type: object
  
  Context-specific recovery action, including sending capacity or prepaid funding recovery, and StartHostedCheckoutAction on a bank-verification card refusal from POST /v1/my/subscription.

- `code` (required)
  Type: integer

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (optional)
  Type: string; nullable
  
  Optional machine-readable error reason.

- `provisioning_id` (optional)
  Type: integer; nullable
  
  Existing provisioning row involved in a managed-account conflict.

- `retryable` (optional)
  Type: boolean
  
  Whether retrying the same idempotent operation can succeed.

- `retry_at` (optional)
  Type: string, date-time
  
  Earliest recommended retry time for a retryable failure.

## SignupPromoResult

Type: object

Schema: [SignupPromoResult](https://docs.nitrosend.com/api/schemas/signuppromoresult-244d693d08.md)

- `applied` (required)
  Type: boolean
  
  Whether the code was redeemed.

- `reason` (required)
  Type: string
  
  enum: ["applied","blank","not_found","not_redeemable","plan_not_found","partner_access_revoked"]

- `partner` (required)
  Type: boolean
  
  True when the code made the account a partner (Affiliates tab and Client Management). Partner codes never change the plan.

- `plan_granted` (required)
  Type: boolean
  
  True only when a referral code granted a plan.

- `plan_pending` (optional)
  Type: boolean
  
  True when an optional partner plan offer is being applied after signup.

## StaffPartnerGrantResult

Type: object

Schema: [StaffPartnerGrantResult](https://docs.nitrosend.com/api/schemas/staffpartnergrantresult-3e1386b426.md)

- `status` (required)
  Type: string
  
  enum: ["partner_enabled","already_partner"]

- `message` (required)
  Type: string

- `account_id` (required)
  Type: integer

- `email` (optional)
  Type: string; nullable

- `plan` (optional)
  Type: string; nullable
  
  The account's current plan slug, unchanged by this call.

- `commercial_tier` (optional)
  Type: string; nullable

- `capabilities` (required)
  Type: array
  
  Items:
    Type: string
    
    enum: ["affiliate_center","managed_clients"]

## SignupVerificationRequired

Type: object

Schema: [SignupVerificationRequired](https://docs.nitrosend.com/api/schemas/signupverificationrequired-10eee67b47.md)

- `status` (required)
  Type: string
  
  enum: ["verification_required"]

- `error_code` (optional)
  Type: string
  
  enum: ["verification_required"]

- `next_action` (required)
  Type: string
  
  enum: ["verify_email"]

- `message` (required)
  Type: string

- `error` (optional)
  Type: boolean

- `code` (optional)
  Type: integer

- `verification_expires_in` (optional)
  Type: integer
  
  Example:
  
  ```json
  1800
  ```

## SignupSession

Type: SignupSession

Schema: [SignupSession](https://docs.nitrosend.com/api/schemas/signupsession-e16b022019.md)

allOf:
  Reference: [User](https://docs.nitrosend.com/api/schemas/user-b512d97e7c.md); Type: object

  Type: object
  
  - `meta` (optional)
    Type: object
    
    - `account_id` (optional)
      Type: integer; nullable
    
    - `promo` (optional)
      Reference: [SignupPromoResult](https://docs.nitrosend.com/api/schemas/signuppromoresult-244d693d08.md); Type: object

## User

Type: object

Schema: [User](https://docs.nitrosend.com/api/schemas/user-b512d97e7c.md)

- `id` (optional)
  Type: integer

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `email` (optional)
  Type: string, email

- `email_verified_at` (optional)
  Type: string, date-time; nullable
  
  Actual email proof time; legacy access does not fabricate proof.

- `unconfirmed_email` (optional)
  Type: string, email; nullable
  
  Requested email change awaiting proof. Continue signing in with email until confirmation.

- `signup_completed_at` (optional)
  Type: string, date-time; nullable

- `mobile` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `time_zone` (optional)
  Type: string; nullable

- `admin` (optional)
  Type: boolean

- `ui_login_count` (optional)
  Type: integer
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Impersonator

Type: object

Schema: [Impersonator](https://docs.nitrosend.com/api/schemas/impersonator-29bed20d4d.md)

- `id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `name` (optional)
  Type: string; nullable

## ImpersonationStatus

Type: object

Schema: [ImpersonationStatus](https://docs.nitrosend.com/api/schemas/impersonationstatus-aeed4cfe3b.md)

- `impersonating` (required)
  Type: boolean

- `impersonator` (required)
  Type: unknown
  
  oneOf:
    Reference: [Impersonator](https://docs.nitrosend.com/api/schemas/impersonator-29bed20d4d.md); Type: object
  
    Type: null

## ImpersonationExit

Type: object

Schema: [ImpersonationExit](https://docs.nitrosend.com/api/schemas/impersonationexit-41e1119d4e.md)

- `redirect_url` (required)
  Type: string, uri
  
  Example:
  
  ```json
  "https://api.nitrosend.com/adm"
  ```

## ManagedAccountLifecycleStatus

Type: 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.

Schema: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md)

enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

## ManagedAccountLifecycleStatusFilter

Type: string

Schema: [ManagedAccountLifecycleStatusFilter](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatusfilter-5852c68708.md)

enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended","needs_setup"]

## ManagedAccountProvisioning

Type: object

Schema: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md)

- `id` (required)
  Type: integer

- `external_ref` (required)
  Type: string
  
  maxLength: 128

- `source` (required)
  Type: string
  
  enum: ["dashboard","partner_api"]

- `status` (required)
  Reference: [ManagedAccountLifecycleStatus](https://docs.nitrosend.com/api/schemas/managedaccountlifecyclestatus-6752f4797f.md); Type: 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.
  
  enum: ["preparing","awaiting_owner","payment_required","setup","active","payment_issue","ended"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `allowed_actions` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["send_invitation","resend_invitation","send_payment_reminder","enter","release"]

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

- `managed_on_setup` (required)
  Type: boolean
  
  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_paid` (required)
  Type: boolean
  
  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.

- `owner` (required)
  Type: object
  
  - `email` (required)
    Type: string, email

- `invitation` (required)
  Type: object
  
  - `expired` (required)
    Type: boolean
  
  - `expires_at` (required)
    Type: string, date-time
  
  - `deadline_at` (required)
    Type: string, date-time
  
  - `notice_sent_at` (required)
    Type: string, date-time; nullable
  
  - `claimed_at` (required)
    Type: string, date-time; nullable
  
  - `reissues_remaining` (required)
    Type: integer
    
    minimum: 0
    
    maximum: 3

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

## ManagedAccountProvisioningCreated

Type: ManagedAccountProvisioningCreated

Schema: [ManagedAccountProvisioningCreated](https://docs.nitrosend.com/api/schemas/managedaccountprovisioningcreated-5c46bea353.md)

allOf:
  Reference: [ManagedAccountProvisioning](https://docs.nitrosend.com/api/schemas/managedaccountprovisioning-8880e78f23.md); Type: object

  Type: object
  
  - `idempotent_replay` (required)
    Type: boolean

## DashboardManagedAccountCreateRequest

Type: object

Schema: [DashboardManagedAccountCreateRequest](https://docs.nitrosend.com/api/schemas/dashboardmanagedaccountcreaterequest-820244c8df.md)

- `managed_account` (required)
  Type: object
  
  - `owner_email` (required)
    Type: string, email
  
  - `owner_first_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `owner_last_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `account_name` (required)
    Type: string
    
    maxLength: 120

## PartnerManagedAccountCreateRequest

Type: object

Schema: [PartnerManagedAccountCreateRequest](https://docs.nitrosend.com/api/schemas/partnermanagedaccountcreaterequest-4c62de1c94.md)

- `managed_account` (required)
  Type: object
  
  - `external_ref` (required)
    Type: string
    
    maxLength: 128
  
  - `owner_email` (required)
    Type: string, email
  
  - `owner_first_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `owner_last_name` (optional)
    Type: string
    
    maxLength: 100
  
  - `account_name` (required)
    Type: string
    
    maxLength: 120

## AccountProvisioningCredential

Type: object

Schema: [AccountProvisioningCredential](https://docs.nitrosend.com/api/schemas/accountprovisioningcredential-a324087370.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  maxLength: 120

- `scopes` (required)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: string
    
    enum: ["provision","manage"]

- `secret_hint` (required)
  Type: string

- `expires_at` (required)
  Type: string, date-time

- `last_used_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `created_at` (required)
  Type: string, date-time

## AccountProvisioningCredentialIssued

Type: AccountProvisioningCredentialIssued

Schema: [AccountProvisioningCredentialIssued](https://docs.nitrosend.com/api/schemas/accountprovisioningcredentialissued-686c0a6700.md)

allOf:
  Reference: [AccountProvisioningCredential](https://docs.nitrosend.com/api/schemas/accountprovisioningcredential-a324087370.md); Type: object

  Type: object
  
  - `secret` (required)
    Type: string
    
    One-time nspk_live_ credential secret.
    
    writeOnly: true

## AccountProvisioningCredentialCreateRequest

Type: object

Schema: [AccountProvisioningCredentialCreateRequest](https://docs.nitrosend.com/api/schemas/accountprovisioningcredentialcreaterequest-485636e9e1.md)

- `credential` (required)
  Type: object
  
  - `name` (required)
    Type: string
    
    maxLength: 120
  
  - `scopes` (required)
    Type: array
    
    minItems: 1
    
    uniqueItems: true
    
    Items:
      Type: string
      
      enum: ["provision","manage"]
  
  - `expires_at` (optional)
    Type: string, date-time

## AccountManagementCredential

Type: object

Schema: [AccountManagementCredential](https://docs.nitrosend.com/api/schemas/accountmanagementcredential-62a442ea85.md)

- `id` (required)
  Type: integer

- `account_management_grant_id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  maxLength: 120

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `secret_hint` (required)
  Type: string

- `expires_at` (required)
  Type: string, date-time

- `last_used_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `created_at` (required)
  Type: string, date-time

- `brand` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `sid` (required)
    Type: string
  
  - `name` (required)
    Type: string

## AccountManagementCredentialIssued

Type: AccountManagementCredentialIssued

Schema: [AccountManagementCredentialIssued](https://docs.nitrosend.com/api/schemas/accountmanagementcredentialissued-ccc873a72c.md)

allOf:
  Reference: [AccountManagementCredential](https://docs.nitrosend.com/api/schemas/accountmanagementcredential-62a442ea85.md); Type: object

  Type: object
  
  - `secret` (required)
    Type: string
    
    One-time nsmc_live_ credential secret.
    
    writeOnly: true

## AccountManagementCredentialCreateRequest

Type: object

Schema: [AccountManagementCredentialCreateRequest](https://docs.nitrosend.com/api/schemas/accountmanagementcredentialcreaterequest-1f48d1e92b.md)

- `credential` (required)
  Type: object
  
  - `name` (required)
    Type: string
    
    maxLength: 120
  
  - `brand_sid` (optional)
    Type: string
    
    Defaults to the managed Account's default Brand.
  
  - `expires_at` (optional)
    Type: string, date-time
    
    Defaults to 90 days and cannot exceed one year.

## ManagedAccountClaimRequest

Type: object

Schema: [ManagedAccountClaimRequest](https://docs.nitrosend.com/api/schemas/managedaccountclaimrequest-9a4b0bb9dd.md)

- `claim` (required)
  Type: object
  
  - `token` (required)
    Type: string
    
    writeOnly: true

## ManagedAccountClaimCompletionRequest

Type: object

Schema: [ManagedAccountClaimRequest](https://docs.nitrosend.com/api/schemas/managedaccountclaimrequest-9a4b0bb9dd.md)

- `claim` (required)
  Type: object
  
  - `token` (required)
    Type: string
    
    writeOnly: true

## ManagedAccountClaimInspection

Type: object

Schema: [ManagedAccountClaimInspection](https://docs.nitrosend.com/api/schemas/managedaccountclaiminspection-22c1590231.md)

- `manager` (required)
  Type: object
  
  - `name` (optional)
    Type: string; nullable

- `managed_account` (required)
  Type: object
  
  - `name` (optional)
    Type: string; nullable

- `owner_email` (required)
  Type: string
  
  Masked owner address

- `expires_at` (required)
  Type: string, date-time

- `authentication` (required)
  Type: string
  
  const: "login_required"

## ManagedAccountClaimCompletion

Type: object

Schema: [ManagedAccountClaimCompletion](https://docs.nitrosend.com/api/schemas/managedaccountclaimcompletion-76dbe5b244.md)

- `claimed` (required)
  Type: boolean
  
  const: true

- `status` (required)
  Type: string
  
  The agency's management access. active on Setup mode does not mean paid; read payment_required.
  
  enum: ["payment_required","active","manager_disabled"]

- `payment_required` (required)
  Type: boolean
  
  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_setup` (required)
  Type: boolean
  
  The client account is on Setup mode.

- `managed_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (required)
    Type: string; nullable

## Account

Type: object

Schema: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `avatar` (optional)
  Type: string; nullable
  
  Signed blob ID

- `banner` (optional)
  Type: string; nullable
  
  Signed blob ID

- `commercial_tier` (optional)
  Type: string
  
  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.
  
  enum: ["unsubscribed","free","setup","starter","pro","growth","scale","ultra","enterprise"]

- `safe_mode_enabled` (optional)
  Type: boolean

- `access` (optional)
  Reference: [AccountAccess](https://docs.nitrosend.com/api/schemas/accountaccess-afca59462c.md); Type: object

- `billing` (optional)
  Type: unknown
  
  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.
  
  oneOf:
    Reference: [AccountBilling](https://docs.nitrosend.com/api/schemas/accountbilling-0761bdeffb.md); Type: object
    
    Billing for direct access (owners, admins and members, and their own credentials).
  
    Reference: [DelegatedAccountBilling](https://docs.nitrosend.com/api/schemas/delegatedaccountbilling-1d025108d9.md); Type: 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.

- `team` (optional)
  Type: object
  
  Present for direct access and omitted from delegated account projections.
  
  - `seat_limit` (optional)
    Type: integer
  
  - `seat_count` (optional)
    Type: integer
  
  - `member_count` (optional)
    Type: integer
  
  - `invite_count` (optional)
    Type: integer
  
  - `current_role` (optional)
    Type: string; nullable
  
  - `can_manage_team` (optional)
    Type: boolean

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## AccountBilling

Type: object

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

Schema: [AccountBilling](https://docs.nitrosend.com/api/schemas/accountbilling-0761bdeffb.md)

- `access_policy` (required)
  Type: string; nullable
  
  enum: ["free_allowed","paid_required"]

- `plan_name` (optional)
  Type: string; nullable

- `plan` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [Plan](https://docs.nitrosend.com/api/schemas/plan-fa8ed0bdab.md); Type: object

- `spend_cap_monthly_cents` (optional)
  Type: integer; nullable
  
  minimum: 0

- `comped` (optional)
  Type: boolean

- `overage` (optional)
  Type: object
  
  Additional properties: true

- `entitlements` (optional)
  Reference: [BillingEntitlements](https://docs.nitrosend.com/api/schemas/billingentitlements-6434d07335.md); Type: object

- `resources` (optional)
  Type: object
  
  - `email` (optional)
    Reference: [AccountResourceUsage](https://docs.nitrosend.com/api/schemas/accountresourceusage-399adbf672.md); Type: object
  
  - `sms` (optional)
    Reference: [AccountResourceUsage](https://docs.nitrosend.com/api/schemas/accountresourceusage-399adbf672.md); Type: object
  
  - `ai` (optional)
    Reference: [AccountResourceUsage](https://docs.nitrosend.com/api/schemas/accountresourceusage-399adbf672.md); Type: object

- `funding` (required)
  Type: object
  
  Additional properties: true

- `provider_route` (required)
  Type: object
  
  Additional properties: true

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

- `outstanding_invoice` (optional)
  Type: object; nullable
  
  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.
  
  - `id` (optional)
    Type: integer; nullable
    
    The newest unpaid invoice. Null only when no invoice record exists for the unpaid balance.

- `brands` (required)
  Type: object
  
  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.
  
  - `used` (optional)
    Type: integer
  
  - `limit` (optional)
    Type: integer
    
    Effective brand capacity including purchased units. 0 means unlimited when unlimited is true.
  
  - `remaining` (optional)
    Type: integer; nullable
    
    Null when unlimited is true.
  
  - `unlimited` (optional)
    Type: boolean
  
  - `can_create` (optional)
    Type: boolean
    
    True when plan headroom allows creating another brand.

- `domains` (optional)
  Type: object
  
  Account-wide customer sending-domain capacity, including purchased units. Brand-subdomain senders do not consume these slots.
  
  - `limit` (required)
    Type: integer; nullable
  
  - `used` (required)
    Type: integer
  
  - `remaining` (required)
    Type: integer; nullable
  
  - `unlimited` (required)
    Type: boolean
  
  - `can_add` (required)
    Type: boolean

- `lifetime` (optional)
  Type: object
  
  - `email_sent` (optional)
    Type: integer
  
  - `sms_sent` (optional)
    Type: integer
  
  - `ai_used` (optional)
    Type: integer

## DelegatedAccountBilling

Type: 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.

Schema: [DelegatedAccountBilling](https://docs.nitrosend.com/api/schemas/delegatedaccountbilling-1d025108d9.md)

- `access_policy` (required)
  Type: string; nullable
  
  enum: ["free_allowed","paid_required"]

- `plan` (required)
  Type: unknown; nullable
  
  allOf:
    Reference: [Plan](https://docs.nitrosend.com/api/schemas/plan-fa8ed0bdab.md); Type: object

- `subscription_status` (required)
  Type: string; nullable
  
  enum: ["pending","active","inactive","canceled","free_tier"]

- `commercial_tier` (required)
  Type: string
  
  enum: ["unsubscribed","free","setup","starter","pro","growth","scale","ultra","enterprise"]

- `provider_route` (required)
  Type: object
  
  Additional properties: true

Additional properties: false

## SendingPause

Type: 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.

Schema: [SendingPause](https://docs.nitrosend.com/api/schemas/sendingpause-17f8373ff7.md)

- `sending_paused` (required)
  Type: boolean
  
  enum: [true]

- `reason` (optional)
  Type: string
  
  Present only for an explained deliverability pause.
  
  enum: ["critical_bounce_rate","critical_complaint_rate"]

- `occurred_at` (required)
  Type: string, date-time

- `headline` (required)
  Type: string

- `detail` (required)
  Type: string

- `what_to_do` (optional)
  Type: array
  
  Present only for an explained deliverability pause.
  
  Items:
    Type: string

- `request_review` (required)
  Type: string
  
  The instruction an agent relays to the owner.

- `recovery_actions` (required)
  Type: array
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
      
      enum: ["verify_list","request_review","contact_support"]
    
    - `label` (required)
      Type: string
    
    - `url` (required)
      Type: string
      
      App link or support mailto.

## AccountResourceUsage

Type: object

Schema: [AccountResourceUsage](https://docs.nitrosend.com/api/schemas/accountresourceusage-399adbf672.md)

- `used` (required)
  Type: integer

- `allowance` (required)
  Type: integer; nullable

- `remaining` (required)
  Type: integer; nullable

- `overage_rate` (required)
  Type: number

- `mode` (required)
  Type: string
  
  enum: ["budget","monthly","unlimited"]

- `budget` (required)
  Type: integer; nullable

- `budget_used` (required)
  Type: integer

## AccountAccess

Type: object

Schema: [AccountAccess](https://docs.nitrosend.com/api/schemas/accountaccess-afca59462c.md)

- `source` (required)
  Type: string
  
  enum: ["owner","membership","platform_admin","delegated","management_credential","api_key","shopify"]

- `delegated` (required)
  Type: boolean

- `manager_account_id` (optional)
  Type: integer

- `manager_account_name` (optional)
  Type: string; nullable

- `management_grant_id` (optional)
  Type: integer

- `permission_set` (optional)
  Type: string
  
  enum: ["operator_v1"]

- `credential_type` (optional)
  Type: string
  
  enum: ["management"]

## AccountManagementGrant

Type: object

Schema: [AccountManagementGrant](https://docs.nitrosend.com/api/schemas/accountmanagementgrant-d8259a8074.md)

- `id` (required)
  Type: integer

- `status` (required)
  Type: string
  
  enum: ["pending","active","revoked","released"]

- `permission_set` (required)
  Type: string
  
  enum: ["operator_v1"]

- `manager_account` (required)
  Type: object
  
  - `id` (required)
    Type: integer
  
  - `name` (optional)
    Type: string; nullable

- `requested_at` (required)
  Type: string, date-time

- `activated_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `released_at` (optional)
  Type: string, date-time; nullable

## AccountManagementGrantCommand

Type: object

Schema: [AccountManagementGrantCommand](https://docs.nitrosend.com/api/schemas/accountmanagementgrantcommand-4ae97ecfc8.md)

- `management_grant_id` (required)
  Type: integer
  
  Exact grant returned by the show endpoint; prevents a stale command from targeting a replacement grant.

## AccountTeam

Type: object

Schema: [AccountTeam](https://docs.nitrosend.com/api/schemas/accountteam-f67c1a5055.md)

- `account` (optional)
  Reference: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md); Type: object

- `memberships` (optional)
  Type: array
  
  Items:
    Reference: [AccountMembership](https://docs.nitrosend.com/api/schemas/accountmembership-1cc598e779.md); Type: object

- `invites` (optional)
  Type: array
  
  Items:
    Reference: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md); Type: object

- `accessible_accounts` (optional)
  Type: array
  
  Items:
    Reference: [Account](https://docs.nitrosend.com/api/schemas/account-7e1b0d5641.md); Type: object

## AccountMembership

Type: object

Schema: [AccountMembership](https://docs.nitrosend.com/api/schemas/accountmembership-1cc598e779.md)

- `id` (optional)
  Type: integer

- `role` (optional)
  Type: string
  
  enum: ["member","admin","owner"]

- `user_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `name` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## AccountInvite

Type: object

Schema: [AccountInvite](https://docs.nitrosend.com/api/schemas/accountinvite-d8cf429662.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `role` (optional)
  Type: string
  
  enum: ["member","admin"]

- `token` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["pending","accepted","revoked","expired"]

- `accepted_at` (optional)
  Type: string, date-time; nullable

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `expires_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Subscription

Type: object

Schema: [Subscription](https://docs.nitrosend.com/api/schemas/subscription-4999c6c6c7.md)

- `id` (optional)
  Type: integer

- `plan_id` (optional)
  Type: integer

- `plan_name` (optional)
  Type: string; nullable
  
  Current package name. Historical purchase labels are retained in billing records.

- `billing_provider` (optional)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `source_billing_provider` (optional)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `billing_migration_required` (optional)
  Type: boolean

- `manage_url` (optional)
  Type: string, uri; nullable

- `spend_cap_monthly_cents` (optional)
  Type: integer; nullable
  
  Merchant-selected monthly cap for metered usage charges.
  
  minimum: 0

- `shopify_usage_metered` (optional)
  Type: boolean
  
  Whether the active Shopify plan has at least one configured usage meter.

- `status` (optional)
  Type: string
  
  enum: ["pending","active","inactive","canceled","free_tier"]

- `interval` (optional)
  Type: string
  
  enum: ["month","year","week","day"]

- `currency` (optional)
  Type: string

- `subtotal_cents` (optional)
  Type: integer

- `tax_cents` (optional)
  Type: integer

- `total_cents` (optional)
  Type: integer

- `base_price_cents` (optional)
  Type: integer

- `discount_cents` (optional)
  Type: integer
  
  Per-period Stripe discount in cents (0 when none).

- `next_payment_cents` (optional)
  Type: integer
  
  Amount billed next period

- `discount_end_at` (optional)
  Type: string, date-time; nullable
  
  When the discount stops (null for forever/once or no discount).

- `activated` (optional)
  Type: boolean

- `entitlements` (optional)
  Reference: [BillingEntitlements](https://docs.nitrosend.com/api/schemas/billingentitlements-6434d07335.md); Type: object

## BillingEntitlements

Type: object

Schema: [BillingEntitlements](https://docs.nitrosend.com/api/schemas/billingentitlements-6434d07335.md)

- `agent_inbox` (required)
  Reference: [AgentInboxEntitlement](https://docs.nitrosend.com/api/schemas/agentinboxentitlement-b7d2714327.md); Type: object

## AgentInboxEntitlement

Type: object

Schema: [AgentInboxEntitlement](https://docs.nitrosend.com/api/schemas/agentinboxentitlement-b7d2714327.md)

- `enabled` (required)
  Type: boolean

- `max_inboxes` (required)
  Type: integer; nullable
  
  Account-wide exact-inbox capacity. Null means contract-defined unlimited capacity.
  
  minimum: 0

- `included_inboxes` (optional)
  Type: integer; nullable
  
  Effective included allowance
  
  minimum: 0

- `grandfathered_inboxes` (optional)
  Type: integer
  
  minimum: 0

- `purchased_inboxes` (optional)
  Type: integer
  
  Confirmed paid units only.
  
  minimum: 0

- `coexistence_inboxes` (optional)
  Type: integer
  
  Paid onward-copy capacity for enrolled inboxes receiving through Nitrosend MX. Does not apply to provider-primary forwarding.
  
  minimum: 0

- `inbound_messages_included` (required)
  Type: integer; nullable
  
  minimum: 0

- `inbound_messages_metered` (required)
  Type: boolean

- `inbound_message_overage_rate_cents` (required)
  Type: string
  
  pattern: "^\\d+(\\.\\d+)?$"

- `max_inbound_domains` (required)
  Type: integer; nullable
  
  minimum: 0

- `max_apex_domains` (required)
  Type: integer; nullable
  
  minimum: 0

- `apex_mx` (required)
  Type: boolean

- `legacy_forwarding` (required)
  Type: boolean

- `catch_all` (required)
  Type: boolean

- `retention_days` (required)
  Type: integer; nullable
  
  minimum: 0

- `advanced_queue_controls` (required)
  Type: boolean

## SubscriptionCreateRequest

Type: object

Schema: [SubscriptionCreateRequest](https://docs.nitrosend.com/api/schemas/subscriptioncreaterequest-d5e60ab175.md)

- `plan_id` (required)
  Type: integer

- `stripe_token` (optional)
  Type: string; nullable
  
  Stripe card token for paid-plan creation.

- `coupon_code` (optional)
  Type: string; nullable
  
  Customer-entered Stripe promotion code or coupon ID. Refused on an agency operator's purchase for a client account.

## DelegatedSubscription

Type: 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.

Schema: [DelegatedSubscription](https://docs.nitrosend.com/api/schemas/delegatedsubscription-e2844fb27a.md)

- `id` (required)
  Type: integer

- `plan_id` (required)
  Type: integer

- `plan_name` (required)
  Type: string; nullable

- `status` (required)
  Type: string
  
  enum: ["pending","active","inactive","canceled","free_tier"]

- `interval` (required)
  Type: string
  
  enum: ["month","year","week","day"]

- `currency` (required)
  Type: string

- `activated` (required)
  Type: boolean

- `base_price_cents` (required)
  Type: integer

- `billing_provider` (required)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `source_billing_provider` (required)
  Type: string; nullable
  
  enum: ["shopify","stripe","stripe_projects","vercel","aws"]

- `billing_route` (required)
  Type: object
  
  Additional properties: true

- `plan` (required)
  Type: unknown; nullable
  
  allOf:
    Reference: [Plan](https://docs.nitrosend.com/api/schemas/plan-fa8ed0bdab.md); Type: object

Additional properties: false

## FundingPurchaseCreateRequest

Type: object

Schema: [FundingPurchaseCreateRequest](https://docs.nitrosend.com/api/schemas/fundingpurchasecreaterequest-75107d5668.md)

- `amount_cents` (required)
  Type: integer
  
  Integer service value in minor currency units.
  
  minimum: 1

- `currency` (optional)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `instrument` (optional)
  Type: string
  
  Optional hosted funding instrument. Omit to use the account default.
  
  enum: ["stripe_checkout","shopify_one_time"]

- `paid_action_intent_id` (optional)
  Type: string; nullable
  
  Optional opaque continuation bound to this funding purchase.

Additional properties: false

## FundingInstrument

Type: object

Schema: [FundingInstrument](https://docs.nitrosend.com/api/schemas/fundinginstrument-238033d568.md)

- `instrument` (required)
  Type: string
  
  enum: ["stripe_checkout","shopify_one_time"]

- `provider` (required)
  Type: string
  
  enum: ["stripe","shopify"]

- `mode` (required)
  Type: string
  
  enum: ["hosted_approval"]

- `available` (required)
  Type: boolean

- `reason` (optional)
  Type: string; nullable

Additional properties: false

## FundingUrlApproval

Type: object

Schema: [FundingUrlApproval](https://docs.nitrosend.com/api/schemas/fundingurlapproval-de5aa5cd2e.md)

- `kind` (required)
  Type: string
  
  enum: ["url"]

- `provider` (required)
  Type: string
  
  enum: ["stripe","shopify"]

- `url` (required)
  Type: string, uri

- `target` (required)
  Type: string
  
  enum: ["self","top"]

Additional properties: false

## FundingChallengeApproval

Type: object

Schema: [FundingChallengeApproval](https://docs.nitrosend.com/api/schemas/fundingchallengeapproval-e14e6c1951.md)

- `kind` (required)
  Type: string
  
  enum: ["challenge"]

- `instrument` (required)
  Type: string

- `protocol` (required)
  Type: string

- `challenge` (required)
  Type: string

- `expires_at` (optional)
  Type: string, date-time; nullable

Additional properties: false

## FundingApproval

Type: FundingApproval

Schema: [FundingApproval](https://docs.nitrosend.com/api/schemas/fundingapproval-b915497dc1.md)

oneOf:
  Reference: [FundingUrlApproval](https://docs.nitrosend.com/api/schemas/fundingurlapproval-de5aa5cd2e.md); Type: object

  Reference: [FundingChallengeApproval](https://docs.nitrosend.com/api/schemas/fundingchallengeapproval-e14e6c1951.md); Type: object

## FundingPurchase

Type: object

Schema: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md)

- `id` (required)
  Type: integer

- `paid_action_intent_id` (optional)
  Type: string; nullable

- `provider` (required)
  Type: string
  
  enum: ["stripe","shopify"]

- `instrument` (required)
  Type: string
  
  enum: ["stripe_checkout","shopify_one_time","stripe_off_session"]

- `status` (required)
  Type: string
  
  enum: ["requested","pending","checkout_created","credited","failed","expired","partially_reversed","reversed"]

- `currency` (required)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `requested_cents` (required)
  Type: integer
  
  minimum: 1

- `requested_display` (optional)
  Type: string

- `checkout_url` (optional)
  Type: string, uri; nullable

- `approval` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [FundingApproval](https://docs.nitrosend.com/api/schemas/fundingapproval-b915497dc1.md); Type: FundingApproval

- `expires_at` (optional)
  Type: string, date-time; nullable

- `credited_cents` (required)
  Type: integer
  
  minimum: 0

- `reversed_cents` (required)
  Type: integer
  
  minimum: 0

- `created_at` (required)
  Type: string, date-time

- `updated_at` (required)
  Type: string, date-time

Additional properties: false

## FundingPurchaseCapability

Type: object

Schema: [FundingPurchaseCapability](https://docs.nitrosend.com/api/schemas/fundingpurchasecapability-9fb3ffa1d8.md)

- `available` (required)
  Type: boolean

- `state` (required)
  Type: string

- `reason` (optional)
  Type: string; nullable

- `default_instrument` (optional)
  Type: string; nullable
  
  enum: ["stripe_checkout","shopify_one_time"]

- `instruments` (required)
  Type: array
  
  Items:
    Reference: [FundingInstrument](https://docs.nitrosend.com/api/schemas/fundinginstrument-238033d568.md); Type: object

- `currency` (required)
  Type: string

- `minimum_cents` (optional)
  Type: integer; nullable

- `maximum_cents` (optional)
  Type: integer; nullable

- `preset_cents` (required)
  Type: array
  
  Items:
    Type: integer

Additional properties: false

## FundingStatus

Type: object

Schema: [FundingStatus](https://docs.nitrosend.com/api/schemas/fundingstatus-b79b1e333b.md)

- `state` (required)
  Type: string

- `applies_to` (required)
  Type: string
  
  enum: ["prepaid_features"]

- `subscription_gate` (required)
  Type: boolean

- `currency` (required)
  Type: string

- `available_cents` (required)
  Type: integer

- `reserved_cents` (required)
  Type: integer

- `deficit_cents` (required)
  Type: integer

- `purchase` (required)
  Reference: [FundingPurchaseCapability](https://docs.nitrosend.com/api/schemas/fundingpurchasecapability-9fb3ffa1d8.md); Type: object

- `pending_purchase` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md); Type: object

Additional properties: true

## FundingPurchaseResponse

Type: object

Schema: [FundingPurchaseResponse](https://docs.nitrosend.com/api/schemas/fundingpurchaseresponse-f77d32410d.md)

- `purchase` (required)
  Reference: [FundingPurchase](https://docs.nitrosend.com/api/schemas/fundingpurchase-6388e04b71.md); Type: object

- `funding` (required)
  Reference: [FundingStatus](https://docs.nitrosend.com/api/schemas/fundingstatus-b79b1e333b.md); Type: object

Additional properties: false

## SubscriptionChangeRequest

Type: object

Schema: [SubscriptionChangeRequest](https://docs.nitrosend.com/api/schemas/subscriptionchangerequest-9820d6506c.md)

- `plan_id` (required)
  Type: integer

- `coupon_code` (optional)
  Type: string; nullable
  
  Customer-entered Stripe promotion code or coupon ID.

## SubscriptionCouponPreviewRequest

Type: object

Schema: [SubscriptionCouponPreviewRequest](https://docs.nitrosend.com/api/schemas/subscriptioncouponpreviewrequest-bdb93fff78.md)

- `plan_id` (required)
  Type: integer

- `coupon_code` (required)
  Type: string
  
  Customer-entered Stripe promotion code or coupon ID.

## SubscriptionCouponPreview

Type: object

Schema: [SubscriptionCouponPreview](https://docs.nitrosend.com/api/schemas/subscriptioncouponpreview-f8bacf6139.md)

- `code` (required)
  Type: string

- `discount_label` (required)
  Type: string

- `discount_cents` (required)
  Type: integer

- `subtotal_cents` (required)
  Type: integer

- `tax_cents` (required)
  Type: integer

- `total_cents` (required)
  Type: integer

- `total_after_discount_cents` (required)
  Type: integer

- `currency` (required)
  Type: string

## OAuthPopupAccount

Type: object

Schema: [OAuthPopupAccount](https://docs.nitrosend.com/api/schemas/oauthpopupaccount-aaffe1b73b.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string

- `access` (optional)
  Reference: [AccountAccess](https://docs.nitrosend.com/api/schemas/accountaccess-afca59462c.md); Type: object

- `can_manage` (optional)
  Type: boolean

- `has_campaign` (optional)
  Type: boolean
  
  Whether the account has made any campaign. This alone does not determine onboarding eligibility.

- `setup_brand` (optional)
  Type: object; nullable
  
  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.
  
  - `sid` (required)
    Type: string
  
  - `suggested_site` (optional)
    Type: string; nullable
  
  - `brand_color` (required)
    Type: string

- `needs_subscribe` (required)
  Type: boolean

- `plans` (optional)
  Type: array
  
  Offers available through this account's provider, including retained Free terms when eligible.
  
  Items:
    Reference: [Plan](https://docs.nitrosend.com/api/schemas/plan-fa8ed0bdab.md); Type: object

## OAuthPopupPlan

Type: object

Schema: [OAuthPopupPlan](https://docs.nitrosend.com/api/schemas/oauthpopupplan-91cd787e2f.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string

- `slug` (required)
  Type: string

- `base_price_cents` (required)
  Type: integer

- `interval` (optional)
  Type: string; nullable

- `tier_group` (optional)
  Type: string

## OAuthPopupContext

Type: object

Schema: [OAuthPopupContext](https://docs.nitrosend.com/api/schemas/oauthpopupcontext-3e0eea70a1.md)

- `application_name` (optional)
  Type: string; nullable

- `email` (optional)
  Type: string
  
  The signed-in person's address, where an agent's first test goes.

- `accounts` (required)
  Type: array
  
  Items:
    Reference: [OAuthPopupAccount](https://docs.nitrosend.com/api/schemas/oauthpopupaccount-aaffe1b73b.md); Type: object

- `plans` (required)
  Type: array
  
  Items:
    Reference: [OAuthPopupPlan](https://docs.nitrosend.com/api/schemas/oauthpopupplan-91cd787e2f.md); Type: object

- `stripe_publishable_key` (optional)
  Type: string; nullable

## OAuthPopupSubscribeRequest

Type: object

Schema: [OAuthPopupSubscribeRequest](https://docs.nitrosend.com/api/schemas/oauthpopupsubscriberequest-d7e8777501.md)

- `plan_id` (required)
  Type: integer

- `account_id` (optional)
  Type: integer; nullable

- `stripe_token` (optional)
  Type: string; nullable

## OAuthPopupSubscribeResponse

Type: object

Schema: [OAuthPopupSubscribeResponse](https://docs.nitrosend.com/api/schemas/oauthpopupsubscriberesponse-61bd3748f0.md)

- `next_step` (required)
  Type: string
  
  enum: ["consent"]

## FirstTouchAttributionContext

Type: 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.

Schema: [FirstTouchAttributionContext](https://docs.nitrosend.com/api/schemas/firsttouchattributioncontext-13e66f28c9.md)

- `landing_url` (optional)
  Type: string; nullable

- `referrer_url` (optional)
  Type: string; nullable

- `captured_at` (optional)
  Type: string, date-time; nullable

- `utm_source` (optional)
  Type: string; nullable

- `utm_medium` (optional)
  Type: string; nullable

- `utm_campaign` (optional)
  Type: string; nullable

- `utm_content` (optional)
  Type: string; nullable

- `utm_term` (optional)
  Type: string; nullable

- `fbclid` (optional)
  Type: string; nullable
  
  Meta click identifier (fbclid) from the first touch, subject to the click-identifier rules above.

- `ttclid` (optional)
  Type: string; nullable
  
  TikTok click identifier (ttclid) from the first touch, subject to the click-identifier rules above.

## OAuthLaunchRequest

Type: object

Schema: [OAuthLaunchRequest](https://docs.nitrosend.com/api/schemas/oauthlaunchrequest-ccb6184314.md)

- `provider` (required)
  Type: string
  
  enum: ["google_oauth2","github"]

- `auth_intent` (optional)
  Type: string
  
  default: "app"
  
  enum: ["app","agent"]

- `auth_step` (optional)
  Type: string
  
  default: "login"
  
  enum: ["login","signup"]

- `resume_url` (optional)
  Type: string, uri; nullable
  
  Required when `auth_intent=agent`; must point to the frontend `/oauth/connect` route.

- `invite_token` (optional)
  Type: string; nullable

- `referral_code` (optional)
  Type: string; nullable

- `rewardful_referral_id` (optional)
  Type: string; nullable

- `attribution_context` (optional)
  Reference: [FirstTouchAttributionContext](https://docs.nitrosend.com/api/schemas/firsttouchattributioncontext-13e66f28c9.md); Type: 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.

- `signup_intent` (optional)
  Reference: [SignupIntent](https://docs.nitrosend.com/api/schemas/signupintent-30dbbeb7e4.md); Type: string; nullable
  
  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.
  
  enum: ["agency"]

## SignupIntent

Type: string; nullable

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.

Schema: [SignupIntent](https://docs.nitrosend.com/api/schemas/signupintent-30dbbeb7e4.md)

enum: ["agency"]

## OAuthLaunchResponse

Type: object

Schema: [OAuthLaunchResponse](https://docs.nitrosend.com/api/schemas/oauthlaunchresponse-e938698fe1.md)

- `launch_url` (required)
  Type: string, uri

## Brand

Type: object

Schema: [Brand](https://docs.nitrosend.com/api/schemas/brand-090ed4316f.md)

- `id` (optional)
  Type: integer

- `sid` (optional)
  Type: string
  
  Public secure identifier (non-sequential)
  
  readOnly: true

- `account_id` (optional)
  Type: integer

- `brand_color` (optional)
  Type: string; nullable

- `text_color` (optional)
  Type: string; nullable

- `bg_color` (optional)
  Type: string; nullable

- `radius` (optional)
  Type: integer; nullable
  
  minimum: 0
  
  maximum: 64

- `spacing_density` (optional)
  Type: string; nullable
  
  enum: ["compact","normal","spacious"]

- `font_heading` (optional)
  Type: string; nullable

- `font_body` (optional)
  Type: string; nullable

- `heading_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 48

- `body_size` (optional)
  Type: integer; nullable
  
  minimum: 12
  
  maximum: 20

- `brand_document` (optional)
  Type: string; nullable
  
  maxLength: 15360

- `company_description` (optional)
  Type: string; nullable

- `default_header` (optional)
  Type: object; nullable

- `default_footer` (optional)
  Type: object; nullable

- `default_theme` (optional)
  Type: object; nullable

- `physical_address` (optional)
  Type: string; nullable

- `company_name` (optional)
  Type: string; nullable

- `source_url` (optional)
  Type: string; nullable

- `last_scraped_at` (optional)
  Type: string, date-time; nullable

- `links` (optional)
  Type: array; nullable
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string
    
    - `icon` (optional)
      Type: string
    
    - `title` (optional)
      Type: string

- `logo` (optional)
  Type: string; nullable
  
  Logo URL

- `complete` (optional)
  Type: boolean
  
  True when brand_color and company_name are set

- `email_from_name` (optional)
  Type: string; nullable

- `email_from_email` (optional)
  Type: string; nullable

- `email_reply_to` (optional)
  Type: string; nullable

- `from_email_domain_status` (optional)
  Type: string
  
  Authorization state of the configured visible From address.
  
  enum: ["blank","verified","unverified"]

- `effective_from_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_reply_to` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `effective_sending_domain` (optional)
  Type: string; nullable
  
  readOnly: true

- `effective_source_email` (optional)
  Type: string, email; nullable
  
  readOnly: true

- `sender_configured` (optional)
  Type: boolean
  
  readOnly: true

- `email_view_online` (optional)
  Type: boolean
  
  Default-off brand setting that injects a campaign view-in-browser link when a verified tracking domain is available.

- `email_view_online_placement` (optional)
  Type: string
  
  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.
  
  enum: ["top","footer"]

- `email_track_opens` (optional)
  Type: boolean
  
  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_clicks` (optional)
  Type: boolean
  
  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_recipients` (optional)
  Type: array
  
  Items:
    Type: string, email

- `onboarding_state` (optional)
  Type: object
  
  JSONB — keys are step names, values are completion metadata
  
  Additional properties: true

- `onboarding` (optional)
  Type: object
  
  - `steps` (optional)
    Type: object
    
    Current state of each onboarding step
  
  - `progress` (optional)
    Type: object
    
    - `completed` (optional)
      Type: integer
    
    - `total` (optional)
      Type: integer

- `domain_verified` (optional)
  Type: boolean

- `can_send` (optional)
  Type: boolean

- `brand_subdomain` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

- `byo_routing` (optional)
  Type: object
  
  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.
  
  - `mismatch` (optional)
    Type: boolean
  
  - `provider` (optional)
    Type: string; nullable
    
    The connected BYO provider, e.g. ses.
  
  - `bypassing_domains` (optional)
    Type: array
    
    Verified domains still sending through Nitrosend's hosted provider.
    
    Items:
      Type: string
  
  - `message` (optional)
    Type: string; nullable

- `subscribed_contacts_count` (optional)
  Type: integer
  
  Count of subscribed contacts in this brand, recounted in the background at most every 10 minutes while the brand is listed or fetched.

- `logo_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `logo_tone` (optional)
  Type: string; nullable
  
  Measured from the logo. A light mark on transparent gets a header band in emails.
  
  enum: ["light","dark"]
  
  readOnly: true

- `logo_aspect` (optional)
  Type: number; nullable
  
  The logo's width over its height. Emails fit the logo to one header height.
  
  readOnly: true

- `screenshot_url` (optional)
  Type: string, uri; nullable
  
  readOnly: true

- `capabilities` (optional)
  Type: object
  
  Additional properties: true

- `sms_provisioned` (optional)
  Type: boolean
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## BrandSubdomain

Type: object

Schema: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md)

- `namespace_status` (required)
  Type: string
  
  enum: ["unreserved","active","replacement_pending","retiring","retired"]

- `status` (required)
  Type: string
  
  enum: ["brand_identity_required","brand_identity_review_required","namespace_reservation_required","not_materialized","root_unavailable","ready","unavailable"]

- `ready` (required)
  Type: boolean

- `selected` (optional)
  Type: boolean

- `preparation_required` (required)
  Type: boolean

- `from_email` (optional)
  Type: string, email

- `fqdn` (optional)
  Type: string

- `apex` (optional)
  Type: string

- `local_part` (optional)
  Type: string

- `local_part_editable` (optional)
  Type: boolean

- `fqdn_changeable` (optional)
  Type: boolean
  
  Whether the current hosted address offers a rename. The write still enforces pending work and claim allowances.

- `suggested_subdomain` (optional)
  Type: string; nullable
  
  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.

- `message` (optional)
  Type: string
  
  Only with `status: brand_identity_required`: the next step, naming the missing fields. The same sentence the prepare_sending refusal carries.

## BrandSubdomainPreparationResponse

Type: object

Schema: [BrandSubdomainPreparationResponse](https://docs.nitrosend.com/api/schemas/brandsubdomainpreparationresponse-760add0860.md)

- `status` (required)
  Type: string
  
  enum: ["ready","unavailable"]

- `brand_subdomain` (required)
  Reference: [BrandSubdomain](https://docs.nitrosend.com/api/schemas/brandsubdomain-70129532d1.md); Type: object

## AudienceReachFit

Type: object

Schema: [AudienceReachFit](https://docs.nitrosend.com/api/schemas/audiencereachfit-d5771ef0b5.md)

- `plan_id` (required)
  Type: integer

- `slug` (required)
  Type: string

- `name` (required)
  Type: string

- `tier_group` (required)
  Type: string

- `daily_cap` (optional)
  Type: integer; nullable
  
  Recipients per 24 hours at the account's sending standing; null when unlimited

- `capacity` (optional)
  Type: integer; nullable
  
  Emails available within the month: what remains on the current plan, the first month's allowance on a candidate; null when unlimited

- `days_to_reach` (optional)
  Type: integer; nullable
  
  Days until everyone has been reached once; null when the month cannot hold the send

- `covers` (required)
  Type: boolean
  
  Whether one full send to the audience fits within the month

## AudienceReach

Type: object

Schema: [AudienceReach](https://docs.nitrosend.com/api/schemas/audiencereach-106eff5b94.md)

- `audience` (required)
  Type: integer

- `cohort` (required)
  Type: string
  
  The account's deliverability cohort the daily caps are read at

- `current` (optional)
  Type: unknown; nullable
  
  The current plan; null when the account has no subscription
  
  allOf:
    Reference: [AudienceReachFit](https://docs.nitrosend.com/api/schemas/audiencereachfit-d5771ef0b5.md); Type: object

- `recommended` (optional)
  Type: unknown; nullable
  
  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
  
  allOf:
    Reference: [AudienceReachFit](https://docs.nitrosend.com/api/schemas/audiencereachfit-d5771ef0b5.md); Type: object

- `covered` (required)
  Type: boolean
  
  Whether the current plan covers a full send

- `summary` (optional)
  Type: string; nullable
  
  The one sentence every surface shows; null when covered

## HostedSenderAvailability

Type: object

Schema: [HostedSenderAvailability](https://docs.nitrosend.com/api/schemas/hostedsenderavailability-ac1d44a545.md)

- `subdomain` (required)
  Type: string
  
  The normalised label that would be reserved (or the input when unsafe)

- `fqdn` (optional)
  Type: string; nullable

- `available` (required)
  Type: boolean

- `reason` (optional)
  Type: string; nullable
  
  Why the address is unavailable; null when available
  
  enum: ["taken","unsafe","reserved","local_part_invalid"]

- `local_part` (optional)
  Type: string; nullable
  
  The normalised local part that would be reserved (the allocator's default when none was given), or the input when it is invalid.

- `from_email` (optional)
  Type: string; nullable
  
  The exact address that would be reserved; null when unavailable for a policy reason

## BrandDeletionSafetyImpact

Type: object

Schema: [BrandDeletionSafetyImpact](https://docs.nitrosend.com/api/schemas/branddeletionsafetyimpact-849b0a5a1d.md)

- `contacts` (required)
  Type: integer
  
  minimum: 0

- `campaigns` (required)
  Type: integer
  
  minimum: 0

- `flows` (required)
  Type: integer
  
  minimum: 0

- `templates` (required)
  Type: integer
  
  minimum: 0

- `domains` (required)
  Type: integer
  
  minimum: 0

- `messages` (required)
  Type: integer
  
  minimum: 0

## BrandDeletionSafetyActiveSends

Type: object

Schema: [BrandDeletionSafetyActiveSends](https://docs.nitrosend.com/api/schemas/branddeletionsafetyactivesends-7e42fa03b3.md)

- `queued_messages` (required)
  Type: integer
  
  minimum: 0

- `active_campaigns` (required)
  Type: integer
  
  Scheduled or live campaigns.
  
  minimum: 0

## BrandDeletionSafety

Type: object

Schema: [BrandDeletionSafety](https://docs.nitrosend.com/api/schemas/branddeletionsafety-6483c513a8.md)

- `deletion_impact` (required)
  Reference: [BrandDeletionSafetyImpact](https://docs.nitrosend.com/api/schemas/branddeletionsafetyimpact-849b0a5a1d.md); Type: object

- `active_sends` (required)
  Reference: [BrandDeletionSafetyActiveSends](https://docs.nitrosend.com/api/schemas/branddeletionsafetyactivesends-7e42fa03b3.md); Type: object

- `can_delete` (required)
  Type: boolean
  
  True when no force confirmation is required.

- `requires_force` (required)
  Type: boolean
  
  True when active sends require `force=true` to delete.

## AffiliateCenterPayload

Type: object

Schema: [AffiliateCenterPayload](https://docs.nitrosend.com/api/schemas/affiliatecenterpayload-833d1dde5c.md)

- `enrolled` (required)
  Type: boolean
  
  Whether the account is linked to a Rewardful affiliate.

- `available` (required)
  Type: boolean
  
  Whether live affiliate data or setup is currently available.

- `state` (optional)
  Type: string; nullable
  
  enum: ["active","paused","unavailable"]

- `setup_status` (optional)
  Type: string; nullable
  
  Present only while an entitled, unlinked account is being reconciled.
  
  enum: ["pending","needs_details","unavailable"]

- `share_url` (optional)
  Type: string, uri; nullable

- `stats` (optional)
  Type: object
  
  - `visitors` (optional)
    Type: integer
    
    minimum: 0
  
  - `leads` (optional)
    Type: integer
    
    minimum: 0
  
  - `conversions` (optional)
    Type: integer
    
    minimum: 0

- `earnings` (optional)
  Type: object
  
  - `known` (optional)
    Type: boolean
  
  - `total_cents` (optional)
    Type: integer; nullable
  
  - `currency` (optional)
    Type: string

## BrandWebsiteInput

Type: object

Schema: [BrandWebsiteInput](https://docs.nitrosend.com/api/schemas/brandwebsiteinput-e152cc1e28.md)

- `url` (required)
  Type: string
  
  Real business website. HTTPS is added when no scheme is supplied. Reserved example websites are rejected before scanning.

## BrandScanAdmission

Type: object

Schema: [BrandScanAdmission](https://docs.nitrosend.com/api/schemas/brandscanadmission-c86217fed3.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","scraping"]

- `url` (required)
  Type: string

- `scan_id` (required)
  Type: string

- `idempotent_replay` (optional)
  Type: boolean

## BrandScanStatus

Type: object

Schema: [BrandScanStatus](https://docs.nitrosend.com/api/schemas/brandscanstatus-63f98dd6f9.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","completed","failed","unknown"]

- `scan_id` (required)
  Type: string; nullable

- `kind` (optional)
  Type: string
  
  enum: ["website","kit"]

- `url` (optional)
  Type: string

- `error` (optional)
  Type: string

- `preview` (optional)
  Type: object
  
  Additional properties: true

## SetupCenterPayload

Type: object

Schema: [SetupCenterPayload](https://docs.nitrosend.com/api/schemas/setupcenterpayload-84155dd467.md)

- `next_actions` (optional)
  Type: array
  
  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.
  
  Items:
    Type: object
    
    - `id` (required)
      Type: string
      
      enum: ["brand","sender","address","contacts","custom_domain","agent"]
    
    - `blocking` (required)
      Type: boolean
    
    - `scope` (optional)
      Type: string
      
      enum: ["email","campaigns_and_flows"]
    
    - `state` (required)
      Type: string
      
      enum: ["action_required","recommended","waiting"]

- `cards` (optional)
  Type: array
  
  Items:
    Reference: [SetupCenterCard](https://docs.nitrosend.com/api/schemas/setupcentercard-299d2987e3.md); Type: object

- `sections` (optional)
  Type: object
  
  - `required` (optional)
    Type: array
    
    Items:
      Type: string
  
  - `recommended` (optional)
    Type: array
    
    Items:
      Type: string

- `progress` (optional)
  Type: object
  
  Counts the three required cards: Brand Kit, contacts and the first audience email. Agent connection and owner previews do not count.
  
  - `completed` (optional)
    Type: integer
  
  - `total` (optional)
    Type: integer

- `seen` (optional)
  Type: boolean

- `dismissed` (optional)
  Type: boolean

- `complete` (optional)
  Type: boolean

- `established` (optional)
  Type: boolean
  
  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_email` (optional)
  Type: object; nullable
  
  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.
  
  - `state` (optional)
    Type: string
    
    `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.
    
    enum: ["queued","writing","sending","sent","written","skipped","failed"]
  
  - `campaign_id` (optional)
    Type: integer; nullable
  
  - `sent_at` (optional)
    Type: string, date-time; nullable
  
  - `to` (optional)
    Type: string; nullable

- `suggested_site` (optional)
  Type: string; nullable
  
  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_choice` (optional)
  Type: string; nullable
  
  Who a first real send comes from, once asked.
  
  enum: ["own","hosted"]

- `contact_source` (optional)
  Type: object; nullable
  
  The mail tools the last scan found evidence of on the brand's site.
  
  - `site` (optional)
    Type: string
  
  - `tools` (optional)
    Type: array
    
    Items:
      Type: string
      
      enum: ["mailchimp","klaviyo","hubspot","mailerlite","brevo","activecampaign","shopify"]

- `suggested_address` (optional)
  Type: object; nullable
  
  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.
  
  - `site` (optional)
    Type: string
  
  - `address` (optional)
    Type: string
  
  - `page` (optional)
    Type: string
    
    Where on the site it was found, as host and path (allbirds.com/pages/contact).

- `first_kit` (optional)
  Type: boolean
  
  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.
  
  readOnly: true

- `can_email_sign_in_link` (optional)
  Type: boolean
  
  Present on authenticated UI snapshots. Whether this requester is the fresh account owner eligible to request the saved draft link; the command rechecks authorization and draft ownership.
  
  readOnly: true

- `current_scan` (optional)
  Type: object; nullable
  
  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.
  
  - `scan_id` (required)
    Type: string
  
  - `kind` (required)
    Type: string
    
    enum: ["website","kit","brief"]
  
  - `url` (optional)
    Type: string
  
  - `started_at` (required)
    Type: string, date-time
  
  - `status` (required)
    Type: string
    
    enum: ["scanning","completed","failed","unknown"]
  
  - `applied` (required)
    Type: boolean
  
  - `error` (optional)
    Type: string

## SetupCenterCard

Type: object

Schema: [SetupCenterCard](https://docs.nitrosend.com/api/schemas/setupcentercard-299d2987e3.md)

- `id` (optional)
  Type: string
  
  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.
  
  enum: ["brand_kit_scan","import_subscribers","first_email","connect_agent","dns"]

- `complete` (optional)
  Type: boolean

- `acknowledged` (optional)
  Type: boolean

- `acknowledged_at` (optional)
  Type: string, date-time; nullable

- `client` (optional)
  Type: string; nullable
  
  `connect_agent` only: the agent that connected first, as the API names clients (for example `Claude Code`).

- `clients` (optional)
  Type: array
  
  `connect_agent` only: the agents connected now, one per live MCP connection, by the same names. Agents the API cannot name are left out.
  
  Items:
    Type: string

## FieldCatalog

Type: object

Schema: [FieldCatalog](https://docs.nitrosend.com/api/schemas/fieldcatalog-51b67420ab.md)

- `id` (required)
  Type: integer

- `key` (required)
  Type: string
  
  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`).
  

- `category` (required)
  Type: string
  
  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)
  
  
  enum: ["contact","custom","enrichment","engagement","tag"]

- `field_type` (required)
  Type: string
  
  Inferred from the first observed value; pinned and never flipped.
  
  enum: ["string","number","boolean","date","enum"]

- `presentation_type` (required)
  Type: string
  
  Shared presentation contract used by fact displays and generated merge tags.
  
  enum: ["text","number","currency","percent","date","datetime","boolean","enum"]

- `presentation_options` (required)
  Type: object
  
  Provider-supplied formatting metadata such as decimal precision,
  currency-code field path, unit scale, or percentage multiplier.
  
  
  Additional properties: true

- `label` (required)
  Type: string
  
  Human-readable label. Defaults to a humanised version of the key.

- `display_label` (optional)
  Type: string
  
  Source-qualified field label suitable for display.

- `source_key` (optional)
  Type: string; nullable

- `source_name` (optional)
  Type: string; nullable

- `object_label` (optional)
  Type: string; nullable

- `source_field_label` (optional)
  Type: string; nullable

- `merge_tag` (optional)
  Type: string; nullable
  
  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.
  

- `promoted` (required)
  Type: boolean
  
  Whether this field is pinned as a default column in the contacts grid.

- `fill_rate` (optional)
  Type: string; nullable
  
  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:
  
  ```json
  "75.0"
  ```

- `fill_rate_refreshed_at` (optional)
  Type: string, date-time; nullable
  
  When fill_rate was last computed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## DeliveryCapacity

Type: object

Schema: [DeliveryCapacity](https://docs.nitrosend.com/api/schemas/deliverycapacity-bff017be39.md)

- `source` (optional)
  Type: string
  
  enum: ["plan","operator_override"]

- `window_seconds` (optional)
  Type: integer
  
  const: 86400

- `status` (required)
  Type: string
  
  enum: ["known","unlimited","not_applicable","unknown","degraded"]

- `limit` (required)
  Type: integer; nullable
  
  minimum: 0

- `reserved` (required)
  Type: integer; nullable
  
  minimum: 0

- `accepted` (required)
  Type: integer; nullable
  
  minimum: 0

- `provider_unknown` (required)
  Type: integer; nullable
  
  minimum: 0

- `remaining` (required)
  Type: integer; nullable
  
  minimum: 0

Additional properties: false

## SharedAbuseCapacity

Type: object

Retired shared probation allowance. Status is always not_applicable; the field remains for compatibility.

Schema: [SharedAbuseCapacity](https://docs.nitrosend.com/api/schemas/sharedabusecapacity-89ccf276b4.md)

- `status` (required)
  Type: string
  
  enum: ["available","deferred","not_applicable","unknown","degraded"]

- `reason_code` (optional)
  Type: string
  
  const: "signup_sending_capacity_reached"

- `retry_at` (optional)
  Type: string, date-time

Additional properties: false

## DeliveryPacingScope

Type: object

Schema: [DeliveryPacingScope](https://docs.nitrosend.com/api/schemas/deliverypacingscope-84fb8b5c87.md)

- `type` (required)
  Type: string

- `key` (optional)
  Type: string

- `status` (required)
  Type: string
  
  enum: ["ready","deferred"]

- `next_dispatch_at` (optional)
  Type: string, date-time

- `minimum_interval_seconds` (required)
  Type: number
  
  minimum: 0

- `baseline_rate_per_second` (optional)
  Type: number
  
  minimum: 0

- `effective_rate_per_second` (optional)
  Type: number
  
  minimum: 0

- `cooldown_reason` (optional)
  Type: string

- `cooldown_until` (optional)
  Type: string, date-time

- `feedback_epoch` (required)
  Type: integer
  
  minimum: 0

Additional properties: false

## DeliveryPacingState

Type: object

Schema: [DeliveryPacingState](https://docs.nitrosend.com/api/schemas/deliverypacingstate-b44b7430ca.md)

- `status` (required)
  Type: string
  
  enum: ["ready","deferred"]

- `policy_version` (required)
  Type: string

- `queued_quantity` (optional)
  Type: integer
  
  minimum: 0

- `next_dispatch_at` (optional)
  Type: string, date-time

- `shared_sender` (optional)
  Reference: [SharedSenderStatus](https://docs.nitrosend.com/api/schemas/sharedsenderstatus-9adc282389.md); Type: object

- `initial_bulk_observation` (optional)
  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["observing","deferred"]
  
  - `reason_code` (required)
    Type: string
    
    const: "initial_bulk_observation"
  
  - `retry_at` (required)
    Type: string, date-time
  
  - `label` (required)
    Type: string
  
  - `detail` (required)
    Type: string
  
  Additional properties: false

- `scopes` (required)
  Type: array
  
  Items:
    Reference: [DeliveryPacingScope](https://docs.nitrosend.com/api/schemas/deliverypacingscope-84fb8b5c87.md); Type: object

Additional properties: false

## SharedSenderStatus

Type: object

Schema: [SharedSenderStatus](https://docs.nitrosend.com/api/schemas/sharedsenderstatus-9adc282389.md)

- `status` (required)
  Type: string
  
  enum: ["ready","deferred","paused","degraded"]

- `reason_code` (optional)
  Type: string
  
  enum: ["shared_sender_rate_limited","shared_sender_provider_backpressure","shared_sender_evidence_pending"]

- `retry_at` (optional)
  Type: string, date-time

- `observed_at` (required)
  Type: string, date-time

- `episode_key` (required)
  Type: string

- `label` (required)
  Type: string

- `detail` (required)
  Type: string

- `recovery_actions` (required)
  Type: array
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
      
      enum: ["connect_domain","contact_support"]
    
    - `label` (required)
      Type: string
    
    - `url` (required)
      Type: string, uri
    
    Additional properties: false

Additional properties: false

## DeliveryStatusIssue

Type: object

Schema: [DeliveryStatusIssue](https://docs.nitrosend.com/api/schemas/deliverystatusissue-9621134fee.md)

- `control` (required)
  Type: string
  
  enum: ["account_status","brand","sender_identity","commercial_capacity","shared_abuse_capacity"]

- `reason_code` (required)
  Type: string
  
  enum: ["sending_paused","brand_unavailable","sender_not_ready","sending_capacity_reached","signup_sending_capacity_reached","delivery_evidence_pending"]

- `retryable` (required)
  Type: boolean

- `retry_at` (optional)
  Type: string, date-time

Additional properties: false

## DeliveryStatus

Type: object

Schema: [DeliveryStatus](https://docs.nitrosend.com/api/schemas/deliverystatus-981154d836.md)

- `assessment_scope` (required)
  Type: string
  
  const: "account_capacity"

- `admission_status` (required)
  Type: string
  
  enum: ["allowed","deferred","denied"]

- `sending_pause` (optional)
  Reference: [SendingPause](https://docs.nitrosend.com/api/schemas/sendingpause-17f8373ff7.md); Type: 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.

- `commercial_capacity` (required)
  Reference: [DeliveryCapacity](https://docs.nitrosend.com/api/schemas/deliverycapacity-bff017be39.md); Type: object

- `shared_abuse_capacity` (required)
  Reference: [SharedAbuseCapacity](https://docs.nitrosend.com/api/schemas/sharedabusecapacity-89ccf276b4.md); Type: object
  
  Retired shared probation allowance. Status is always not_applicable; the field remains for compatibility.

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `pacing_state` (required)
  Reference: [DeliveryPacingState](https://docs.nitrosend.com/api/schemas/deliverypacingstate-b44b7430ca.md); Type: object

- `blocking_control` (optional)
  Type: string
  
  enum: ["account_status","brand","sender_identity","commercial_capacity","shared_abuse_capacity"]

- `reason_code` (optional)
  Type: string

- `issues` (required)
  Type: array
  
  Items:
    Reference: [DeliveryStatusIssue](https://docs.nitrosend.com/api/schemas/deliverystatusissue-9621134fee.md); Type: object

- `retry_at` (optional)
  Type: string, date-time

- `observed_at` (required)
  Type: string, date-time

Additional properties: false

## CampaignVersionInput

Type: object

Schema: [CampaignVersionInput](https://docs.nitrosend.com/api/schemas/campaignversioninput-c953708c82.md)

- `subject` (required)
  Type: string
  
  minLength: 1

- `generation_event_id` (optional)
  Type: integer
  
  From a suggested line in readiness `versions.lines`.

- `candidate_locator` (optional)
  Type: string
  
  From a suggested line in readiness `versions.lines`.

Additional properties: false

## CampaignWinnerInput

Type: 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.

Schema: [CampaignWinnerInput](https://docs.nitrosend.com/api/schemas/campaignwinnerinput-cb4e87909a.md)

- `test_share_percent` (required)
  Type: integer
  
  From readiness `versions.test_shares[n].min_bp / 100` up to 95.
  
  minimum: 1
  
  maximum: 95

- `wait_hours` (optional)
  Type: integer
  
  default: 4
  
  enum: [2,4,8,24]

- `measure` (optional)
  Type: string
  
  default: "opens"
  
  enum: ["opens","clicks"]

Additional properties: false

## SubjectVersionOffer

Type: object

Subject line versions for this campaign's audience. Read only.

Schema: [SubjectVersionOffer](https://docs.nitrosend.com/api/schemas/subjectversionoffer-5077e44038.md)

- `eligible` (optional)
  Type: boolean

- `audience_count` (optional)
  Type: integer; nullable

- `max_versions` (optional)
  Type: integer

- `test_shares` (optional)
  Type: object; nullable
  
  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.
  
  Additional properties: 
    Type: object
    
    - `min_bp` (optional)
      Type: integer
    
    - `default_bp` (optional)
      Type: integer
    
    - `winner_available` (optional)
      Type: boolean

- `wait_hours` (optional)
  Type: array
  
  Items:
    Type: integer

- `status` (optional)
  Type: string
  
  enum: ["none","writing","ready","unavailable"]

- `phase` (optional)
  Type: string
  
  While writing: the lines are written and their checks have begun. Absent before that.
  
  enum: ["checking"]

- `reason` (optional)
  Type: string

- `lines` (optional)
  Type: array
  
  Suggested alternatives for the current content.
  
  Items:
    Type: object
    
    - `subject` (optional)
      Type: string
    
    - `approach` (optional)
      Type: string
    
    - `generation_event_id` (optional)
      Type: integer
    
    - `candidate_locator` (optional)
      Type: string

## CampaignExperiment

Type: object

The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

Schema: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md)

- `id` (optional)
  Type: integer

- `recipients` (optional)
  Type: integer

- `mode` (optional)
  Type: string
  
  enum: ["split","winner"]

- `state` (optional)
  Type: string
  
  enum: ["running","awaiting_winner","sending_winner","complete","stopped"]

- `measure` (optional)
  Type: string
  
  enum: ["opens","clicks"]

- `stop_reason` (optional)
  Type: string

- `test_share_percent` (optional)
  Type: number

- `wait_hours` (optional)
  Type: integer

- `decide_at` (optional)
  Type: string, date-time

- `decided_at` (optional)
  Type: string, date-time

- `winner_sent` (optional)
  Type: integer

- `versions` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `key` (optional)
      Type: integer
    
    - `letter` (optional)
      Type: string
    
    - `subject` (optional)
      Type: string
    
    - `own` (optional)
      Type: boolean
    
    - `writer` (optional)
      Type: string
      
      enum: ["owner","ai"]
    
    - `approach` (optional)
      Type: string
    
    - `sent` (optional)
      Type: integer
    
    - `open_rate` (optional)
      Type: number; nullable
    
    - `click_rate` (optional)
      Type: number; nullable
    
    - `unsubscribe_rate` (optional)
      Type: number; nullable
      
      People who unsubscribed after this version was sent, by the horizon, over sent.

- `verdict` (optional)
  Type: object
  
  - `rule` (optional)
    Type: string
  
  - `reason` (optional)
    Type: string
  
  - `winner_key` (optional)
    Type: integer; nullable
  
  - `chosen_key` (optional)
    Type: integer; nullable

## DeliveryReviewBudgetStatus

Type: 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.

Schema: [DeliveryReviewBudgetStatus](https://docs.nitrosend.com/api/schemas/deliveryreviewbudgetstatus-5de71fba0c.md)

- `status` (required)
  Type: string
  
  enum: ["available","exhausted","not_applicable","unavailable"]

- `assessment_scope` (required)
  Type: string
  
  const: "new_content_review"

- `channel` (required)
  Type: string
  
  const: "email"

- `observed_at` (required)
  Type: string, date-time

- `message` (required)
  Type: string

- `note` (required)
  Type: string

- `reason_code` (optional)
  Type: string
  
  const: "delivery_evidence_pending"

- `retry_at` (optional)
  Type: string, date-time
  
  UTC release of the blocking calendar allowance; present when exhausted.

- `remaining` (optional)
  Type: object
  
  - `hour` (required)
    Type: integer
    
    minimum: 0
  
  - `day` (required)
    Type: integer
    
    minimum: 0

- `resets_at` (optional)
  Type: object
  
  - `hour` (required)
    Type: string, date-time
  
  - `day` (required)
    Type: string, date-time

## DeliveryCapacityRecovery

Type: 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.

Schema: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md)

- `state` (required)
  Type: string
  
  enum: ["approaching","reached","campaign_exceeds_remaining"]

- `reason_code` (required)
  Type: string
  
  enum: ["sending_capacity_warning","sending_capacity_reached","signup_sending_capacity_reached"]

- `blocking_control` (required)
  Type: string
  
  enum: ["commercial_capacity","shared_abuse_capacity"]

- `usage_percent` (optional)
  Type: integer
  
  minimum: 0
  
  maximum: 100

- `requested_quantity` (optional)
  Type: integer
  
  minimum: 0

- `label` (required)
  Type: string

- `detail` (required)
  Type: string

- `capacity` (optional)
  Reference: [DeliveryCapacity](https://docs.nitrosend.com/api/schemas/deliverycapacity-bff017be39.md); Type: object

- `upgrade_url` (optional)
  Type: string, uri
  
  Shareable account-specific plan link. Authentication and billing permissions still apply.

- `retry_at` (optional)
  Type: string, date-time
  
  Recorded retry time, not a guarantee that delivery completes then.

- `recovery_action` (optional)
  Reference: [DeliveryCapacityRecoveryAction](https://docs.nitrosend.com/api/schemas/deliverycapacityrecoveryaction-59c89c6f99.md); Type: object

- `recovery_actions` (required)
  Type: array
  
  minItems: 0
  
  Items:
    Reference: [DeliveryCapacityRecoveryAction](https://docs.nitrosend.com/api/schemas/deliverycapacityrecoveryaction-59c89c6f99.md); Type: object

- `owner_action` (optional)
  Reference: [DeliveryCapacityRecoveryAction](https://docs.nitrosend.com/api/schemas/deliverycapacityrecoveryaction-59c89c6f99.md); Type: object

## DeliveryCapacityRecoveryAction

Type: object

Schema: [DeliveryCapacityRecoveryAction](https://docs.nitrosend.com/api/schemas/deliverycapacityrecoveryaction-59c89c6f99.md)

- `type` (required)
  Type: string
  
  enum: ["upgrade_plan","verify_list","contact_owner","manage_provider_billing","contact_support"]

- `label` (required)
  Type: string

- `detail` (optional)
  Type: string

- `url` (required)
  Type: string, uri

- `required_role` (optional)
  Type: string
  
  const: "account_owner_or_admin"

## ValidationAudience

Type: object

Schema: [ValidationAudience](https://docs.nitrosend.com/api/schemas/validationaudience-794b45cf09.md)

- `lead_ids` (optional)
  Type: array
  
  Explicit Lead selection in the current Brand. Does not create marketing Contacts or require a discovery search.
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer
    
    minimum: 1

- `contact_channel_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer

- `contact_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100000
  
  uniqueItems: true
  
  Items:
    Type: integer

- `list_id` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer

- `all_contacts` (optional)
  Type: boolean
  
  All email channels in the current Brand, subject to the 100000-candidate operation bound.
  
  const: true

- `quote_digest` (optional)
  Type: string
  
  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.
  
  pattern: "^[0-9a-f]{64}$"

oneOf:
  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

  Type: unknown

Additional properties: false

## ValidationOperationCounts

Type: object

Schema: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md)

- `candidate_count` (required)
  Type: integer
  
  minimum: 0

- `deduplicated_count` (required)
  Type: integer
  
  minimum: 0

- `cached_count` (required)
  Type: integer
  
  minimum: 0

- `ineligible_count` (required)
  Type: integer
  
  minimum: 0

- `eligible_count` (required)
  Type: integer
  
  minimum: 0

- `pending_count` (optional)
  Type: integer
  
  minimum: 0

- `executing_count` (optional)
  Type: integer
  
  minimum: 0

- `billable_count` (optional)
  Type: integer
  
  minimum: 0

- `not_billable_count` (optional)
  Type: integer
  
  minimum: 0

- `provider_unknown_count` (optional)
  Type: integer
  
  minimum: 0

- `failed_count` (optional)
  Type: integer
  
  minimum: 0

Additional properties: false

## ValidationOperationPricing

Type: object

Schema: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md)

- `price_book_version` (required)
  Type: string

- `unit_rate_cents` (required)
  Type: string

- `included_quantity` (optional)
  Type: integer
  
  minimum: 0

- `maximum_charge_cents` (required)
  Type: integer
  
  minimum: 0

- `committed_cents` (optional)
  Type: integer
  
  minimum: 0

- `released_cents` (optional)
  Type: integer
  
  minimum: 0

- `currency` (required)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `quote_digest` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `expires_at` (required)
  Type: string, date-time

- `execution_deadline_at` (optional)
  Type: string, date-time; nullable

Additional properties: false

## ValidationOperationFunding

Type: object

Schema: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md)

- `route` (required)
  Type: string
  
  const: "direct_prepaid"

- `available` (required)
  Type: boolean

- `reason` (optional)
  Type: string

- `usage_event_id` (optional)
  Type: integer

- `state` (optional)
  Type: string
  
  enum: ["needs_funding","held","committed","released"]

- `recovery` (optional)
  Type: object
  
  Additional properties: true

Additional properties: false

## ValidationOperationQuote

Type: object

Schema: [ValidationOperationQuote](https://docs.nitrosend.com/api/schemas/validationoperationquote-44c858f218.md)

- `status` (required)
  Type: string
  
  enum: ["quoted","needs_funding"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `quote_digest` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `mutation` (required)
  Type: boolean
  
  const: false

Additional properties: false

## ValidationOperation

Type: object

Schema: [ValidationOperation](https://docs.nitrosend.com/api/schemas/validationoperation-3893a00de8.md)

- `operation_id` (required)
  Type: string
  
  minLength: 32
  
  maxLength: 64

- `status` (required)
  Type: string
  
  enum: ["requested","quoted","held","executing","partially_committed","committed","released","needs_funding","failed"]

- `source_kind` (required)
  Type: string
  
  enum: ["contact_channel","contact","list","segment","all_contacts","lead"]

- `item_detail` (required)
  Type: object
  
  - `status` (required)
    Type: string
    
    enum: ["available","compacted"]
  
  - `compacted_at` (optional)
    Type: string, date-time
  
  - `item_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `counts` (required)
  Reference: [ValidationOperationCounts](https://docs.nitrosend.com/api/schemas/validationoperationcounts-8ccb226493.md); Type: object

- `results` (optional)
  Type: object
  
  Per-verdict results across this run's checks and the results it reused. Absent for runs compacted before verdicts were kept.
  
  - `valid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `invalid_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `disposable_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `unknown_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `catchall_count` (optional)
    Type: integer
    
    minimum: 0
  
  Additional properties: false

- `unconfirmed` (optional)
  Type: object
  
  Unknown and catch-all addresses. Left out of sends by default once the run finishes; keepable per run.
  
  - `excluded_count` (optional)
    Type: integer
    
    Addresses this run currently holds out of sends.
    
    minimum: 0
  
  - `sendable_count` (optional)
    Type: integer
    
    This run's unknown and catch-all addresses still in sends.
    
    minimum: 0
  
  - `pending` (optional)
    Type: boolean
    
    The run is still leaving its unconfirmed addresses out.
  
  - `kept_count` (optional)
    Type: integer
    
    minimum: 0
  
  - `kept_at` (optional)
    Type: string, date-time
  
  - `can_include` (optional)
    Type: boolean
    
    Including this run's left-out addresses can be requested now.
  
  - `can_leave_out` (optional)
    Type: boolean
    
    Leaving this run's sendable unconfirmed addresses out can be requested now.
  
  - `include_blocked` (optional)
    Type: boolean
    
    Present and true when sending resumed automatically on the condition unconfirmed addresses stay out. Including them needs support until an operator release.
  
  Additional properties: false

- `pricing` (required)
  Reference: [ValidationOperationPricing](https://docs.nitrosend.com/api/schemas/validationoperationpricing-9c1ba4b128.md); Type: object

- `funding` (required)
  Reference: [ValidationOperationFunding](https://docs.nitrosend.com/api/schemas/validationoperationfunding-a47a55f380.md); Type: object

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

- `failure_code` (optional)
  Type: string

- `started_at` (optional)
  Type: string, date-time

- `completed_at` (optional)
  Type: string, date-time

- `next_action` (optional)
  Type: string

Additional properties: false

## ValidationOperationItem

Type: object

Schema: [ValidationOperationItem](https://docs.nitrosend.com/api/schemas/validationoperationitem-80942f06be.md)

- `id` (required)
  Type: integer

- `contact_channel_id` (optional)
  Type: integer; nullable

- `lead_id` (optional)
  Type: integer; nullable

- `email` (optional)
  Type: string, email
  
  Current address only if it still matches the retained verification identity

- `provider_observed_at` (optional)
  Type: string, date-time; nullable

- `status` (required)
  Type: string
  
  enum: ["pending","executing","billable","not_billable","provider_unknown","failed"]

- `billable` (optional)
  Type: boolean

- `provider` (optional)
  Type: string

- `native_status` (optional)
  Type: string

- `verdict` (optional)
  Type: string

- `failure_code` (optional)
  Type: string

- `result_reference` (optional)
  Type: object
  
  Additional properties: true

- `completed_at` (optional)
  Type: string, date-time

Additional properties: false

## ContactEnrichmentQuote

Type: object

Schema: [ContactEnrichmentQuote](https://docs.nitrosend.com/api/schemas/contactenrichmentquote-8152a7af54.md)

- `quote_digest` (optional)
  Type: string
  
  pattern: "^[a-f0-9]{64}$"

- `selected_count` (required)
  Type: integer

- `already_current_count` (required)
  Type: integer

- `reusable_count` (required)
  Type: integer

- `provider_required_count` (required)
  Type: integer

- `unavailable_count` (required)
  Type: integer

- `maximum_billable_outcomes` (required)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contact_profile_enrichment"]

- `unit_rate_cents` (required)
  Type: string

- `maximum_charge_cents` (required)
  Type: integer

- `currency` (required)
  Type: string
  
  enum: ["USD"]

- `price_book_version` (required)
  Type: string

- `available` (required)
  Type: boolean

- `reason` (optional)
  Type: string; nullable

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

## SpendProjection

Type: object

Schema: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md)

- `schema` (required)
  Type: string
  
  const: "nitrosend.spend.v1"

- `status` (required)
  Type: string
  
  enum: ["ready","needs_funding","payment_pending","blocked","unavailable"]

- `route` (required)
  Type: string
  
  enum: ["direct_prepaid","included","postpaid","shopify","vercel","legacy"]

- `currency` (required)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `maximum_charge_cents` (required)
  Type: integer
  
  minimum: 0

- `balance` (optional)
  Reference: [SpendBalance](https://docs.nitrosend.com/api/schemas/spendbalance-ab3412de2a.md); Type: object

- `funding` (required)
  Type: object
  
  Canonical account funding projection from Billing::Funding::Presenter.
  
  Additional properties: true

- `recovery_action` (required)
  Reference: [SpendRecoveryAction](https://docs.nitrosend.com/api/schemas/spendrecoveryaction-c6fb707fc2.md); Type: object

## PaidActionIntentCreate

Type: object

Schema: [PaidActionIntentCreate](https://docs.nitrosend.com/api/schemas/paidactionintentcreate-9fd9478c78.md)

- `adapter_key` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 100

- `adapter_version` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 32

- `operation_idempotency_key` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 128

- `state_payload` (required)
  Type: object
  
  Adapter-owned state, validated and encrypted before persistence.
  
  Additional properties: true

## PaidActionIntent

Type: object

Schema: [PaidActionIntent](https://docs.nitrosend.com/api/schemas/paidactionintent-d3b8ba9d30.md)

- `id` (required)
  Type: string
  
  Opaque public continuation identifier.
  
  minLength: 32
  
  maxLength: 64

- `schema` (required)
  Type: string
  
  const: "nitrosend.paid_action_intent.v1"

- `status` (required)
  Type: string
  
  enum: ["open","awaiting_funding","ready_to_resume","consumed","cancelled","expired"]

- `adapter` (required)
  Type: object
  
  - `key` (required)
    Type: string
  
  - `version` (required)
    Type: string

- `operation_idempotency_key` (required)
  Type: string

- `original_quote_fingerprint` (required)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `current_quote_fingerprint` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `quote_changed` (optional)
  Type: boolean

- `state_payload` (optional)
  Type: object
  
  Additional properties: true

- `quote` (optional)
  Type: object
  
  Additional properties: true

- `expires_at` (required)
  Type: string, date-time

- `consumed_at` (optional)
  Type: string, date-time; nullable

- `cancelled_at` (optional)
  Type: string, date-time; nullable

## SpendBalance

Type: object

Schema: [SpendBalance](https://docs.nitrosend.com/api/schemas/spendbalance-ab3412de2a.md)

- `available_cents` (required)
  Type: integer

- `reserved_cents` (required)
  Type: integer
  
  minimum: 0

- `shortfall_cents` (required)
  Type: integer
  
  minimum: 0

## SpendRecoveryAction

Type: object

Schema: [SpendRecoveryAction](https://docs.nitrosend.com/api/schemas/spendrecoveryaction-c6fb707fc2.md)

- `type` (optional)
  Type: string
  
  enum: ["add_funds","retry_add_funds","complete_checkout","wait_for_payment","ask_account_admin","manage_in_shopify","manage_in_marketplace","contact_support","unavailable"]

- `reason` (optional)
  Type: string

- `operation` (optional)
  Type: string
  
  enum: ["add_funds"]

- `url` (optional)
  Type: string, uri

- `purchase_id` (optional)
  Type: integer

- `shortfall_cents` (optional)
  Type: integer
  
  minimum: 0

- `minimum_cents` (optional)
  Type: integer
  
  minimum: 0

- `maximum_cents` (optional)
  Type: integer
  
  minimum: 0

- `recommended_cents` (optional)
  Type: integer
  
  minimum: 0

- `preset_cents` (optional)
  Type: array
  
  uniqueItems: true
  
  Items:
    Type: integer
    
    minimum: 0

Additional properties: false

## ContactEnrichmentFundingRequired

Type: object

Schema: [ContactEnrichmentFundingRequired](https://docs.nitrosend.com/api/schemas/contactenrichmentfundingrequired-a1729c37a3.md)

- `code` (required)
  Type: string
  
  const: "insufficient_balance"

- `message` (required)
  Type: string

- `error` (required)
  Type: boolean
  
  const: true

- `error_code` (required)
  Type: string
  
  const: "insufficient_balance"

- `currency` (required)
  Type: string
  
  pattern: "^[A-Z]{3}$"

- `required_cents` (required)
  Type: integer
  
  minimum: 0

- `available_cents` (required)
  Type: integer

- `reserved_cents` (required)
  Type: integer
  
  minimum: 0

- `shortfall_cents` (required)
  Type: integer
  
  minimum: 0

- `funding` (required)
  Type: object
  
  Additional properties: true

- `recovery_action` (required)
  Type: object
  
  Additional properties: true

- `spend` (required)
  Reference: [SpendProjection](https://docs.nitrosend.com/api/schemas/spendprojection-3b2e1c7f2c.md); Type: object

## ContactEnrichmentDispatch

Type: object

Schema: [ContactEnrichmentDispatch](https://docs.nitrosend.com/api/schemas/contactenrichmentdispatch-1ed624bab5.md)

- `selected_count` (required)
  Type: integer

- `queued_count` (required)
  Type: integer

- `already_current_count` (required)
  Type: integer

- `reusable_count` (required)
  Type: integer

- `provider_required_count` (required)
  Type: integer

- `unavailable_count` (required)
  Type: integer

- `maximum_charge_cents` (required)
  Type: integer

- `currency` (required)
  Type: string
  
  enum: ["USD"]

- `price_book_version` (required)
  Type: string

- `idempotent_replay` (required)
  Type: boolean

## Contact

Type: object

Schema: [Contact](https://docs.nitrosend.com/api/schemas/contact-2b5c3d2672.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `uuid` (optional)
  Type: string, uuid

- `first_name` (optional)
  Type: string; nullable

- `last_name` (optional)
  Type: string; nullable

- `source` (optional)
  Type: string; nullable

- `country_code` (optional)
  Type: string; nullable

- `flag_emoji` (optional)
  Type: string; nullable
  
  Unicode regional-indicator emoji pair derived from country_code (e.g. "🇦🇺"). Null when country_code is blank.

- `data` (optional)
  Type: object
  
  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:
  
  ```json
  {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  }
  ```
  
  Additional properties: true

- `subscribed_phone` (optional)
  Type: boolean

- `subscribed_email` (optional)
  Type: boolean

- `email` (optional)
  Type: string, email; nullable
  
  Convenience value for the preferred email channel. Full channel detail remains in channels[].

- `subscribed` (optional)
  Type: object
  
  Denormalized subscription summary by channel family.
  
  - `email` (optional)
    Type: boolean
  
  - `phone` (optional)
    Type: boolean

- `verification_status` (optional)
  Type: string
  
  enum: ["verified","suppressed","unverified"]

- `verification_result` (optional)
  Type: string; nullable
  
  Newest list-verification result for the contact's email; null when never checked.
  
  enum: ["valid","invalid","disposable","catchall","unknown",null]

- `enrichment_status` (optional)
  Type: string
  
  enum: ["enriched","not_enriched"]

- `mailbox_provider` (optional)
  Type: string
  
  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.
  
  
  enum: ["gmail","apple","outlook","corporate","unknown"]

- `list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `last_interacted_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `engagement` (optional)
  Type: object; nullable
  
  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.
  
  
  - `rating` (optional)
    Type: string
    
    Five-tier engagement rating based on recency of opens and clicks.
    
    enum: ["engaged","warm","cooling","dormant","never"]
  
  - `emails_sent` (optional)
    Type: integer
  
  - `unique_opens` (optional)
    Type: integer
  
  - `clicks` (optional)
    Type: integer
  
  - `open_rate` (optional)
    Type: number, float; nullable
  
  - `click_rate` (optional)
    Type: number, float; nullable
  
  - `last_opened_at` (optional)
    Type: string, date-time; nullable
  
  - `last_clicked_at` (optional)
    Type: string, date-time; nullable

- `channels` (optional)
  Type: array
  
  Items:
    Reference: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md); Type: object

## ContactChannel

Type: object

Schema: [ContactChannel](https://docs.nitrosend.com/api/schemas/contactchannel-89f5880115.md)

- `id` (optional)
  Type: integer

- `contact_id` (optional)
  Type: integer

- `kind` (optional)
  Type: string
  
  enum: ["email","phone"]

- `value` (optional)
  Type: string

- `subscribed` (optional)
  Type: boolean

- `verified` (optional)
  Type: boolean

- `opt_in_at` (optional)
  Type: string, date-time; nullable

- `opt_out_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `fail_count` (optional)
  Type: integer

- `data` (optional)
  Type: object
  
  Additional properties: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## ImageAsset

Type: object

Schema: [ImageAsset](https://docs.nitrosend.com/api/schemas/imageasset-04f1a1a7d1.md)

- `media_kind` (optional)
  Type: string
  
  enum: ["image"]

- `media_url` (optional)
  Type: string, uri

- `image_url` (optional)
  Type: string, uri

- `signed_id` (optional)
  Type: string

- `filename` (optional)
  Type: string

- `content_type` (optional)
  Type: string

- `byte_size` (optional)
  Type: integer

- `width` (optional)
  Type: integer; nullable
  
  Intrinsic pixel width when detectable.

- `height` (optional)
  Type: integer; nullable
  
  Intrinsic pixel height when detectable.

## ContactList

Type: object

Schema: [ContactList](https://docs.nitrosend.com/api/schemas/contactlist-1538131b0d.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `contacts_count` (optional)
  Type: integer

- `segment_id` (optional)
  Type: integer; nullable

- `stale` (optional)
  Type: boolean

- `last_populated_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## ListDeleteWarning

Type: object

Schema: [ListDeleteWarning](https://docs.nitrosend.com/api/schemas/listdeletewarning-595c1c5082.md)

- `campaign_names` (optional)
  Type: array
  
  Items:
    Type: string

- `flow_names` (optional)
  Type: array
  
  Items:
    Type: string

## BulkListContactsRequest

Type: object

Schema: [BulkListContactsRequest](https://docs.nitrosend.com/api/schemas/bulklistcontactsrequest-04cb14683d.md)

- `action` (required)
  Type: string
  
  Add existing contacts to the list or remove them from it.
  
  enum: ["add","remove"]

- `emails` (required)
  Type: array
  
  minItems: 1
  
  maxItems: 500
  
  Items:
    Type: string, email

## BulkListContactsResponse

Type: object

Schema: [BulkListContactsResponse](https://docs.nitrosend.com/api/schemas/bulklistcontactsresponse-b3c5cc214e.md)

- `action` (optional)
  Type: string
  
  enum: ["add","remove"]

- `list_id` (optional)
  Type: integer

- `added` (optional)
  Type: integer
  
  Contacts newly added for add actions

- `removed` (optional)
  Type: integer
  
  Contacts removed for remove actions

- `already_in_list` (optional)
  Type: array
  
  Items:
    Type: string, email

- `not_in_list` (optional)
  Type: array
  
  Items:
    Type: string, email

- `not_found` (optional)
  Type: array
  
  Items:
    Type: string, email

- `invalid_emails` (optional)
  Type: array
  
  Items:
    Type: string

## DirectUploadCreateRequest

Type: object

Schema: [DirectUploadCreateRequest](https://docs.nitrosend.com/api/schemas/directuploadcreaterequest-7b79eba02f.md)

- `purpose` (optional)
  Type: string
  
  Set to `import` for CSV contact imports, or `image`/`media_asset` for image media assets.
  
  enum: ["import","image","media_asset"]

- `blob` (required)
  Type: object
  
  - `filename` (required)
    Type: string
    
    Example:
    
    ```json
    "contacts.csv"
    ```
  
  - `byte_size` (required)
    Type: integer
    
    Example:
    
    ```json
    1048576
    ```
  
  - `checksum` (required)
    Type: string
    
    Base64-encoded MD5 checksum for Active Storage direct upload.
  
  - `content_type` (optional)
    Type: string
    
    Example:
    
    ```json
    "text/csv"
    ```
  
  - `metadata` (optional)
    Type: object
    
    Additional properties: true

## DirectUpload

Type: object

Schema: [DirectUpload](https://docs.nitrosend.com/api/schemas/directupload-ca32662919.md)

- `signed_id` (optional)
  Type: string
  
  Submit this value to endpoints that consume direct uploads.

- `filename` (optional)
  Type: string

- `byte_size` (optional)
  Type: integer

- `content_type` (optional)
  Type: string; nullable

- `direct_upload` (optional)
  Type: object
  
  - `url` (optional)
    Type: string, uri
  
  - `headers` (optional)
    Type: object
    
    Additional properties: 
      Type: string

## ImportPolicy

Type: object

Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.

Schema: [ImportPolicy](https://docs.nitrosend.com/api/schemas/importpolicy-61a374f358.md)

- `standing` (required)
  Type: string
  
  The account standing the limits derive from.
  
  Example:
  
  ```json
  "trusted"
  ```

- `max_rows` (required)
  Type: integer; nullable
  
  Row ceiling for one import. Null means no row ceiling for this standing.
  
  Example:
  
  ```json
  null
  ```

- `max_file_size_bytes` (required)
  Type: integer
  
  Example:
  
  ```json
  2147483648
  ```

- `max_file_size_mb` (required)
  Type: integer
  
  Example:
  
  ```json
  2048
  ```

- `max_active_imports` (required)
  Type: integer
  
  Example:
  
  ```json
  10
  ```

- `create_rate_limit_per_minute` (required)
  Type: integer
  
  Example:
  
  ```json
  10
  ```

- `direct_upload_rate_limit_per_minute` (required)
  Type: integer
  
  Example:
  
  ```json
  30
  ```

- `write_modes` (required)
  Type: array
  
  Items:
    Type: string
    
    enum: ["real","shadow","dry_run"]

## ImportSpec

Type: object

Schema: [ImportSpec](https://docs.nitrosend.com/api/schemas/importspec-1405feb4a6.md)

- `resource` (required)
  Type: string
  
  enum: ["contacts","leads"]

- `parser` (required)
  Type: string
  
  enum: ["default"]

- `ui` (optional)
  Type: object
  
  Additional properties: true

- `required_rules` (optional)
  Type: object
  
  Additional properties: true

- `fields` (required)
  Type: array
  
  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.
  
  
  Items:
    Type: object
    
    Additional properties: true

- `guardrails` (required)
  Reference: [ImportPolicy](https://docs.nitrosend.com/api/schemas/importpolicy-61a374f358.md); Type: object
  
  Import limits for the authenticated account, derived from its deliverability standing. Clients render these values and never recompute them.

## ImportGuardrail

Type: object

How this import stands against the account's standing row limit.

Schema: [ImportGuardrail](https://docs.nitrosend.com/api/schemas/importguardrail-bcbfe33303.md)

- `tier` (required)
  Type: string
  
  auto when the row count is within the standing limit; contact_us when it is above it and the import halted.
  
  enum: ["auto","contact_us"]

- `status` (required)
  Type: string
  
  Client-facing guardrail status vocabulary.
  
  enum: ["ok","contact_sales"]

- `standing` (required)
  Type: string
  
  The account standing the limit derives from.
  
  Example:
  
  ```json
  "probation"
  ```

- `max_rows` (required)
  Type: integer; nullable
  
  Row ceiling for the standing. Null means no row ceiling.
  
  Example:
  
  ```json
  250000
  ```

## Import

Type: object

Schema: [Import](https://docs.nitrosend.com/api/schemas/import-2cff9baabf.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `parser` (optional)
  Type: string
  
  enum: ["default"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","failed","canceled","complete","contact_us"]

- `total_rows` (optional)
  Type: integer; nullable

- `success_rows` (optional)
  Type: integer; nullable

- `failed_rows` (optional)
  Type: integer; nullable

- `email_rows` (optional)
  Type: object; nullable
  
  Email row results from committed import writes; retries do not double-count ranges. Null for imports without recorded results.
  
  - `subscribed` (optional)
    Type: integer
  
  - `unsubscribed` (optional)
    Type: integer
  
  - `blocked` (optional)
    Type: integer

- `warning_rows` (optional)
  Type: integer
  
  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.

- `progress` (optional)
  Type: object
  
  Canonical live-progress block (the single progress representation). `pct` is the only percent source; a null `pct` means indeterminate.
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `import_errors` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `import_warnings` (optional)
  Type: array
  
  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.
  
  Items:
    Type: array
    
    Items:
      Type: unknown
      
      oneOf:
        Type: integer
      
        Type: string

- `columns` (optional)
  Type: object; nullable
  
  Additional properties: true

- `options` (optional)
  Type: object; nullable
  
  Additional properties: true

- `assigned_list_ids` (optional)
  Type: array
  
  Items:
    Type: integer

- `assigned_lists` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string

- `guardrail` (optional)
  Reference: [ImportGuardrail](https://docs.nitrosend.com/api/schemas/importguardrail-bcbfe33303.md); Type: object
  
  How this import stands against the account's standing row limit.

- `flows_not_started` (optional)
  Type: object; nullable
  
  Live flows this import's committed writes matched but did not start, because options.start_flows was off. Null when none matched.
  
  - `flows` (required)
    Type: array
    
    Items:
      Type: object
      
      - `id` (optional)
        Type: integer
      
      - `name` (optional)
        Type: string
  
  - `message` (required)
    Type: string
  
  - `next_step` (required)
    Type: string

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

## Export

Type: object

Schema: [Export](https://docs.nitrosend.com/api/schemas/export-3664895579.md)

- `id` (optional)
  Type: integer

- `resource` (optional)
  Type: string
  
  enum: ["contacts","leads"]

- `format` (optional)
  Type: string
  
  enum: ["csv"]

- `status` (optional)
  Type: string
  
  enum: ["pending","processing","complete","failed"]

- `total_rows` (optional)
  Type: integer; nullable

- `rows_written` (optional)
  Type: integer
  
  Rows written so far; the live numerator against total_rows.

- `error_message` (optional)
  Type: string; nullable

- `ready` (optional)
  Type: boolean
  
  True once the export is complete and the file is available.

- `download_path` (optional)
  Type: string; nullable
  
  Path to download the CSV; present only when `ready` is true.

- `progress` (optional)
  Type: object
  
  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.
  
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","running","complete","failed"]
  
  - `pct` (optional)
    Type: number; nullable
    
    Completion percentage, or null when indeterminate.
  
  - `stages` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `key` (optional)
        Type: string
      
      - `label` (optional)
        Type: string
      
      - `count` (optional)
        Type: integer; nullable
      
      - `state` (optional)
        Type: string
        
        enum: ["done","active","pending","failed"]

- `started_at` (optional)
  Type: string, date-time; nullable

- `ended_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

## SavedView

Type: object

Schema: [SavedView](https://docs.nitrosend.com/api/schemas/savedview-cb60b3ba7b.md)

- `id` (optional)
  Type: integer

- `surface` (optional)
  Type: string
  
  enum: ["contacts","sending","activity"]

- `name` (optional)
  Type: string

- `visibility` (optional)
  Type: string
  
  enum: ["private","shared"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `layout` (optional)
  Reference: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md); Type: object; nullable
  
  Table layout preset for contacts surface views. Only present when
  surface = contacts.
  

- `owner` (optional)
  Type: boolean
  
  True when the current user is the creator of this view

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## SavedViewLayout

Type: object; nullable

Table layout preset for contacts surface views. Only present when
surface = contacts.


Schema: [SavedViewLayout](https://docs.nitrosend.com/api/schemas/savedviewlayout-9903d0eb2e.md)

- `columns` (optional)
  Type: array
  
  Ordered list of column keys to display
  
  Items:
    Type: string

- `sort` (optional)
  Type: object
  
  - `field` (optional)
    Type: string
    
    Column key to sort by
  
  - `dir` (optional)
    Type: string
    
    Sort direction
    
    enum: ["asc","desc"]

## Segment

Type: object

Schema: [Segment](https://docs.nitrosend.com/api/schemas/segment-29ee089cce.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `origin` (optional)
  Type: string
  
  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.
  
  
  enum: ["user","system"]

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  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.
  

- `cached_count` (optional)
  Type: integer; nullable
  
  Last asynchronously refreshed contact count for this segment.

- `count_computed_at` (optional)
  Type: string, date-time; nullable
  
  When `cached_count` was last refreshed.

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## SegmentFilterExpression

Type: unknown

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.


Schema: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md)

oneOf:
  Reference: [SegmentFilters](https://docs.nitrosend.com/api/schemas/segmentfilters-0ad9c0a44c.md); Type: 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.
  

  Reference: [FlatAndSegmentFilterExpression](https://docs.nitrosend.com/api/schemas/flatandsegmentfilterexpression-2ec627072b.md); Type: object

  Reference: [BooleanSegmentFilterGroup](https://docs.nitrosend.com/api/schemas/booleansegmentfiltergroup-8364897715.md); Type: object

## FlatAndSegmentFilterExpression

Type: object

Schema: [FlatAndSegmentFilterExpression](https://docs.nitrosend.com/api/schemas/flatandsegmentfilterexpression-2ec627072b.md)

- `operator` (required)
  Type: string
  
  enum: ["and"]

- `not` (optional)
  Type: boolean
  
  Legacy flat-AND wrapper does not carry NOT; use BooleanSegmentFilterGroup for NOT.
  
  default: false
  
  enum: [false]

- `children` (required)
  Reference: [SegmentFilters](https://docs.nitrosend.com/api/schemas/segmentfilters-0ad9c0a44c.md); Type: 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.
  

Additional properties: false

## SegmentFilterNode

Type: unknown

Schema: [SegmentFilterNode](https://docs.nitrosend.com/api/schemas/segmentfilternode-f97d1c5f01.md)

oneOf:
  Reference: [AttributeSegmentFilter](https://docs.nitrosend.com/api/schemas/attributesegmentfilter-ae0121b9f0.md); Type: object

  Reference: [EventSegmentFilter](https://docs.nitrosend.com/api/schemas/eventsegmentfilter-2829c99322.md); Type: object

  Reference: [BooleanSegmentFilterGroup](https://docs.nitrosend.com/api/schemas/booleansegmentfiltergroup-8364897715.md); Type: object

## BooleanSegmentFilterGroup

Type: object

Schema: [BooleanSegmentFilterGroup](https://docs.nitrosend.com/api/schemas/booleansegmentfiltergroup-8364897715.md)

- `op` (required)
  Type: string
  
  enum: ["and","or","not"]

- `conditions` (required)
  Type: array
  
  Nested filter nodes. NOT groups must contain exactly one condition.
  
  maxItems: 25
  
  Items:
    Reference: [SegmentFilterNode](https://docs.nitrosend.com/api/schemas/segmentfilternode-f97d1c5f01.md); Type: SegmentFilterNode

Additional properties: false

## SegmentFilters

Type: 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.


Schema: [SegmentFilters](https://docs.nitrosend.com/api/schemas/segmentfilters-0ad9c0a44c.md)

Items:
  Type: unknown
  
  oneOf:
    Reference: [AttributeSegmentFilter](https://docs.nitrosend.com/api/schemas/attributesegmentfilter-ae0121b9f0.md); Type: object
  
    Reference: [EventSegmentFilter](https://docs.nitrosend.com/api/schemas/eventsegmentfilter-2829c99322.md); Type: object

## SegmentPreview

Type: object

Schema: [SegmentPreview](https://docs.nitrosend.com/api/schemas/segmentpreview-69e4423dce.md)

- `count` (optional)
  Type: integer
  
  Live count of contacts matching the supplied filters.

- `sample` (optional)
  Type: array
  
  Bounded contact sample for quick verification.
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: integer
    
    - `email` (optional)
      Type: string; nullable
    
    - `name` (optional)
      Type: string; nullable

- `overlap` (optional)
  Type: array
  
  Bounded overlap with existing segments.
  
  Items:
    Type: object
    
    - `segment_id` (optional)
      Type: integer
    
    - `name` (optional)
      Type: string
    
    - `overlap_count` (optional)
      Type: integer

## AttributeSegmentFilter

Type: object

Schema: [AttributeSegmentFilter](https://docs.nitrosend.com/api/schemas/attributesegmentfilter-ae0121b9f0.md)

- `name` (required)
  Type: string
  
  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_<path>, with dots
  replaced by underscores (for example, data.attio.lifecycle_stage
  becomes contact_data_attio_lifecycle_stage).
  

- `predicate` (required)
  Type: string
  
  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.
  

- `value` (required)
  Type: unknown
  
  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

Type: object

Schema: [EventSegmentFilter](https://docs.nitrosend.com/api/schemas/eventsegmentfilter-2829c99322.md)

- `type` (required)
  Type: string
  
  enum: ["event"]

- `event` (required)
  Type: string
  
  Custom or known event name, e.g. first_send, project_created, checkout.
  
  pattern: "^[a-z][a-z0-9_]{0,63}$"

- `predicate` (required)
  Type: string
  
  enum: ["performed","not_performed","count_at_least","count_at_most"]

- `value` (optional)
  Type: integer
  
  Required for count_at_least and count_at_most.
  
  minimum: 1

- `within_days` (optional)
  Type: integer
  
  Optional rolling event recency window.
  
  minimum: 1

- `since` (optional)
  Type: string, date-time
  
  Optional absolute event recency cutoff.

Must not match:
  Type: unknown

oneOf:
  Type: object
  
  - `predicate` (required)
    Type: string
    
    enum: ["performed","not_performed"]

  Type: object
  
  - `predicate` (required)
    Type: string
    
    enum: ["count_at_least","count_at_most"]

## Campaign

Type: object

Schema: [Campaign](https://docs.nitrosend.com/api/schemas/campaign-268286d2ef.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","active","paused","completed"]

- `approval_state` (optional)
  Type: string

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `name` (optional)
  Type: string

- `data` (optional)
  Type: object
  
  Additional properties: true

- `scheduled_at` (optional)
  Type: string, date-time; nullable

- `sent_count` (optional)
  Type: integer

- `dashboard_url` (optional)
  Type: string, uri; nullable
  
  Canonical dashboard URL with the /my route prefix.

- `preview_url` (optional)
  Type: string, uri; nullable
  
  Signed, expiring public preview URL for the current template version.

- `recipient_snapshot` (optional)
  Type: object; nullable
  
  Last send snapshot. Values are captured at send time and are not a live audience estimate.
  
  - `requested_recipients` (optional)
    Type: integer; nullable
  
  - `dispatched_recipients` (optional)
    Type: integer; nullable
  
  - `blocked_recipients` (optional)
    Type: integer; nullable
  
  - `requested_send_units` (optional)
    Type: integer; nullable
  
  - `dispatched_send_units` (optional)
    Type: integer; nullable
  
  - `units_per_recipient` (optional)
    Type: integer; nullable
  
  - `send_token` (optional)
    Type: string; nullable
  
  - `started_at` (optional)
    Type: string, date-time; nullable
  
  - `completed_at` (optional)
    Type: string, date-time; nullable

- `last_send_recipients` (optional)
  Type: integer; nullable
  
  Alias for the last dispatched recipient snapshot stored in data.recipients.

- `delivery` (optional)
  Type: unknown
  
  Present while a campaign has a current send token; use `/delivery` to poll, refresh progress, and receive polling metadata.
  
  oneOf:
    Reference: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md); Type: object
  
    Type: null

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `editable` (optional)
  Type: boolean
  
  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.
  
  
  readOnly: true

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `trigger` (optional)
  Reference: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md); Type: object

- `template` (optional)
  Type: unknown
  
  oneOf:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object
  
    Type: null

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

## CampaignDeliverySummary

Type: object

Schema: [CampaignDeliverySummary](https://docs.nitrosend.com/api/schemas/campaigndeliverysummary-2455e98bac.md)

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `campaign_send_token` (required)
  Type: string; nullable

- `status` (required)
  Type: string
  
  enum: ["not_started","awaiting_approval","sending","paused","completed","failed","cancelled"]

- `recipients` (required)
  Type: integer
  
  Recipient count captured for the active send.

- `sent` (required)
  Type: integer

- `failed` (required)
  Type: integer

- `pending` (required)
  Type: integer

## CampaignDeliveryProgress

Type: object

Schema: [CampaignDeliveryProgress](https://docs.nitrosend.com/api/schemas/campaigndeliveryprogress-34f8b93607.md)

- `experiment` (optional)
  Reference: [CampaignExperiment](https://docs.nitrosend.com/api/schemas/campaignexperiment-61265bede3.md); Type: object
  
  The test on this send. Rates and the verdict appear only once decided, from the numbers frozen at that time.

- `capacity_recovery` (optional)
  Reference: [DeliveryCapacityRecovery](https://docs.nitrosend.com/api/schemas/deliverycapacityrecovery-04c30c216b.md); Type: 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.

- `stop_reason` (optional)
  Type: string; nullable
  
  Why a stopped send stopped, such as email_under_review for one held by the safety check.

- `safety_review` (optional)
  Type: object; nullable
  
  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.
  
  
  - `how_to_fix` (optional)
    Type: string
  
  - `category` (optional)
    Type: string
  
  - `agent_prompt` (optional)
    Type: string
  
  - `recovery_actions` (optional)
    Type: array
    
    Items:
      Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
  
  - `details` (optional)
    Type: object
    
    For a send it couldn't read, the images and other changes (as SendRefusalDetail details).

- `campaign_send_token` (required)
  Type: string; nullable

- `status` (required)
  Type: string
  
  enum: ["not_started","awaiting_approval","sending","paused","completed","failed","cancelled"]

- `recipients` (required)
  Type: integer
  
  Recipient count captured for the active send.

- `sent` (required)
  Type: integer

- `failed` (required)
  Type: integer

- `pending` (required)
  Type: integer

- `terminal` (required)
  Type: boolean
  
  True when clients can stop polling.

- `poll_after_seconds` (required)
  Type: integer; nullable
  
  Suggested polling delay for active sends.

## MailActionDescription

Type: object

A Mail Action Protocol 0.3 description. The canonical MailSchema core schema is authoritative; this schema restates its shape.


Schema: [MailActionDescription](https://docs.nitrosend.com/api/schemas/mailactiondescription-e8c6bf32cc.md)

- `@context` (required)
  Type: string
  
  enum: ["https://mailschema.org/contexts/map-0.3.jsonld"]

- `@type` (required)
  Type: string
  
  enum: ["MailAction"]

- `@id` (required)
  Type: string, uri
  
  Identifies the interaction.

- `profile` (required)
  Type: string
  
  enum: ["https://mailschema.org/profiles/map/0.3"]

- `type` (required)
  Type: object
  
  - `id` (required)
    Type: string, uri
  
  - `version` (required)
    Type: string
  
  - `contractDigest` (required)
    Type: string
    
    pattern: "^sha-256:[0-9a-f]{64}$"
  
  Additional properties: false

- `issuedAt` (required)
  Type: string, date-time

- `expiresAt` (required)
  Type: string, date-time

- `inLanguage` (required)
  Type: string

- `service` (required)
  Type: object
  
  - `id` (required)
    Type: string, uri
    
    The service's HTTPS origin.
  
  - `tenant` (optional)
    Type: string, uri
  
  Additional properties: false

- `recipient` (required)
  Type: string, email

- `subject` (required)
  Type: object
  
  - `id` (required)
    Type: string, uri
  
  - `title` (required)
    Type: string
  
  Additional properties: false

- `terms` (required)
  Type: object
  
  - `id` (required)
    Type: string, uri
  
  - `version` (required)
    Type: string
    
    Opaque; a decision names it exactly.
  
  Additional properties: false

- `details` (required)
  Type: object
  
  Defined by the type contract's details schema.
  
  Additional properties: true

- `operations` (required)
  Type: array
  
  minItems: 1
  
  maxItems: 32
  
  Items:
    Type: object
    
    - `id` (required)
      Type: string
    
    - `capability` (optional)
      Type: object

- `human` (required)
  Type: object
  
  - `url` (required)
    Type: string, uri
  
  Additional properties: false

Additional properties: false

## SendApproval

Type: object

Schema: [SendApproval](https://docs.nitrosend.com/api/schemas/sendapproval-9ba478f173.md)

- `id` (required)
  Type: integer

- `campaign_id` (required)
  Type: integer

- `can_decide` (required)
  Type: boolean
  
  Whether the signed-in person may decide it, as the account owner or a direct account admin.

- `state` (required)
  Type: string
  
  `withdrawn` means the send stopped before anyone decided. After approval, `delivery_status` tells a send in progress from a finished one.
  
  
  enum: ["pending","approved","declined","expired","withdrawn"]

- `decided_at` (optional)
  Type: string, date-time

- `delivery_status` (required)
  Type: string
  
  enum: ["pending","in_progress","completed","failed","cancelled"]

- `content` (required)
  Type: object
  
  - `subject` (required)
    Type: string
  
  - `preheader` (optional)
    Type: string
  
  - `html` (required)
    Type: string
    
    The exact email the approval sends.
  
  Additional properties: false

- `bcc` (optional)
  Type: string
  
  The address that gets a copy of every email in this send. Each copy consumes an email credit and sending capacity.

- `mail_action` (required)
  Reference: [MailActionDescription](https://docs.nitrosend.com/api/schemas/mailactiondescription-e8c6bf32cc.md); Type: object
  
  The Campaign Send Approval 0.1 description of this send's exact terms.

Additional properties: false

## MessageSendResult

Type: MessageSendResult

Schema: [MessageSendResult](https://docs.nitrosend.com/api/schemas/messagesendresult-ff26fd2684.md)

allOf:
  Reference: [Message](https://docs.nitrosend.com/api/schemas/message-2f77668a9d.md); Type: object

  Type: object
  
  - `ignored_fields` (required)
    Type: array
    
    Top-level request fields Nitrosend doesn't support, sorted. They were ignored; empty when there were none.
    
    
    Items:
      Type: string

## TestSendResult

Type: object

Schema: [TestSendResult](https://docs.nitrosend.com/api/schemas/testsendresult-9d0d94475b.md)

- `outcome` (optional)
  Type: string
  
  Dispatch outcome. New accepted sends return sent. Legacy saved results may use delivered; neither confirms inbox placement.
  
  enum: ["sent","partial","pending","held","failed","dry_run","delivered"]

- `sent` (required)
  Type: integer
  
  Number of tests accepted by the sending provider.

- `pending` (optional)
  Type: integer

- `held` (optional)
  Type: integer
  
  Tests awaiting content review; not sent and not automatically replayed after approval.

- `failed` (optional)
  Type: integer

- `dry_run` (optional)
  Type: boolean

- `results` (required)
  Type: array
  
  Items:
    Type: object
    
    - `email` (optional)
      Type: string
    
    - `success` (optional)
      Type: boolean
      
      The sending provider accepted this test; recipient delivery is separate.
    
    - `status` (optional)
      Type: string
      
      held awaits content review and was not sent; delivered is the legacy acceptance label.
      
      enum: ["sent","delivered","pending","held","failed"]
    
    - `code` (optional)
      Type: string
    
    - `message` (optional)
      Type: string
      
      Human-readable dispatch or provider-feedback detail.
    
    - `error` (optional)
      Type: string
      
      Why this recipient's test was not sent.
    
    - `hold_id` (optional)
      Type: integer
      
      Exact content review case for this test.
    
    - `plan_url` (optional)
      Type: string, 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_fix` (optional)
      Type: string
      
      Explicit recovery guidance; approval alone does not send a test.
    
    - `agent_prompt` (optional)
      Type: string
      
      The reason and fix to paste to an agent
    
    - `recovery_actions` (optional)
      Type: array
      
      Items:
        Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
    
    - `details` (optional)
      Type: object
      
      For a test the safety check couldn't read, each image that failed and the other changes to make.
      
      - `images` (optional)
        Type: array
        
        Items:
          Type: object
      
      - `changes` (optional)
        Type: array
        
        Items:
          Type: object
    
    - `message_id` (optional)
      Type: integer
    
    - `provider_id` (optional)
      Type: string

## Message

Type: object

Schema: [Message](https://docs.nitrosend.com/api/schemas/message-2f77668a9d.md)

- `id` (optional)
  Type: integer

- `channel` (optional)
  Type: string
  
  enum: ["email","sms"]

- `to` (optional)
  Type: string

- `recipients` (optional)
  Type: object
  
  Full normalized email envelope, visible only to authorized account readers. Returned for email messages.
  
  - `to` (optional)
    Type: array
    
    Items:
      Type: string, email
  
  - `cc` (optional)
    Type: array
    
    Items:
      Type: string, email
  
  - `bcc` (optional)
    Type: array
    
    Items:
      Type: string, email

- `subject` (optional)
  Type: string; nullable

- `status` (optional)
  Type: string
  
  enum: ["queued","sent","failed"]

- `provider_id` (optional)
  Type: string; nullable

- `rfc_message_id` (optional)
  Type: string; nullable
  
  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_id` (optional)
  Type: integer; nullable
  
  Source flow ID (null for transactional)

- `source_type` (optional)
  Type: string; nullable
  
  campaign, flow, test, or null (transactional)
  
  enum: ["campaign","flow","test"]

- `source_name` (optional)
  Type: string; nullable
  
  Name of source campaign or flow

- `status_reason_code` (optional)
  Type: string; nullable
  
  Stable reason for a queued or failed dispatch, or the provider feedback on a sent email test.

- `status_reason` (optional)
  Type: string; nullable
  
  Human-readable dispatch or email-test delivery explanation. Recipient-server acceptance does not confirm inbox placement.

- `status_reason_category` (optional)
  Type: string; nullable
  
  Broad category for status_reason.
  
  enum: ["content_review","account","internal","recipient","provider","rate_limit","delivery"]

- `failure_code` (optional)
  Type: string; nullable
  
  Stable machine-readable failure reason; present only when status is failed.

- `failure_reason` (optional)
  Type: string; nullable
  
  Human-readable failure explanation; present only when status is failed.

- `failure_category` (optional)
  Type: string; nullable
  
  Broad category for failure_reason; present only when status is failed.
  
  enum: ["content_review","account","internal","recipient","provider","delivery"]

- `sent_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

## Suppression

Type: object

Account suppression row with bounded source-event diagnostics.

Schema: [Suppression](https://docs.nitrosend.com/api/schemas/suppression-858c847b74.md)

- `id` (optional)
  Type: integer

- `email` (optional)
  Type: string, email

- `reason` (optional)
  Type: string
  
  enum: ["hard_bounce","soft_bounce","complaint","manual","admin","unsubscribe","verification","marketing_withheld","unconfirmed"]

- `scope` (optional)
  Type: string
  
  enum: ["account_scoped","brand_scoped"]

- `brand_id` (optional)
  Type: integer; nullable
  
  Brand affected by a brand-specific stop.

- `active` (optional)
  Type: boolean

- `contact_id` (optional)
  Type: integer; nullable

- `source_provider` (optional)
  Type: string; nullable

- `source_event_id` (optional)
  Type: string; nullable

- `provider_diagnostic` (optional)
  Type: string; nullable
  
  Bounded diagnostic text extracted from the provider feedback event, when retained.

- `bounce_type` (optional)
  Type: string; nullable
  
  enum: ["hard","soft"]

- `bounce_subtype` (optional)
  Type: string; nullable

- `complaint_feedback_type` (optional)
  Type: string; nullable

- `event_occurred_at` (optional)
  Type: string, date-time; nullable

- `expires_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## WebhookEventType

Type: string

Schema: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md)

enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

## Webhook

Type: object

Schema: [Webhook](https://docs.nitrosend.com/api/schemas/webhook-4814f62c10.md)

- `id` (optional)
  Type: integer

- `url` (optional)
  Type: string, uri

- `events` (optional)
  Type: array
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  `failing` while deliveries fail; an endpoint failing for 3 days is turned off.
  
  enum: ["active","failing","disabled"]

- `failing_since` (optional)
  Type: string, date-time; nullable

- `secret` (optional)
  Type: string
  
  Standard Webhooks signing secret (`whsec_...`). Masked unless revealed.

- `last_delivery` (optional)
  Type: object; nullable
  
  - `id` (optional)
    Type: integer
  
  - `event_type` (optional)
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]
  
  - `status` (optional)
    Type: string
    
    enum: ["pending","delivered","failed"]
  
  - `attempts` (optional)
    Type: integer
  
  - `last_response_status` (optional)
    Type: integer; nullable
  
  - `updated_at` (optional)
    Type: string, date-time

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## WebhookWriteRequest

Type: object

Schema: [WebhookWriteRequest](https://docs.nitrosend.com/api/schemas/webhookwriterequest-8251acfea5.md)

- `url` (optional)
  Type: string, uri
  
  HTTPS URL that resolves only to public addresses, without credentials.
  
  maxLength: 2048

- `events` (optional)
  Type: array
  
  minItems: 1
  
  Items:
    Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
    
    enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `enabled` (optional)
  Type: boolean

## WebhookDelivery

Type: object

Schema: [WebhookDelivery](https://docs.nitrosend.com/api/schemas/webhookdelivery-ff6158b877.md)

- `id` (optional)
  Type: integer

- `event_id` (optional)
  Type: string, uuid
  
  Sent as `webhook-id` (`evt_<event_id>`), stable across retries.

- `event_type` (optional)
  Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
  
  enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `status` (optional)
  Type: string
  
  enum: ["pending","delivered","failed"]

- `attempts` (optional)
  Type: integer

- `last_response_status` (optional)
  Type: integer; nullable

- `last_error` (optional)
  Type: string; nullable

- `next_attempt_at` (optional)
  Type: string, date-time

- `payload` (optional)
  Reference: [WebhookEventPayload](https://docs.nitrosend.com/api/schemas/webhookeventpayload-fe6402d1fd.md); Type: object

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## WebhookEventPayload

Type: object

Schema: [WebhookEventPayload](https://docs.nitrosend.com/api/schemas/webhookeventpayload-fe6402d1fd.md)

- `type` (required)
  Reference: [WebhookEventType](https://docs.nitrosend.com/api/schemas/webhookeventtype-8071cb6db3.md); Type: string
  
  enum: ["email.sent","email.delivered","email.bounced","email.complained","email.opened","email.clicked","email.failed","email.received","campaign.completed","campaign.failed","campaign.stopped","flow.paused","sending.paused","sending.limit_approaching","sending.limit_reached","import.completed","import.failed","domain.verified","domain.verification_lost","domain.dns_degraded","webhook.disabled"]

- `timestamp` (required)
  Type: string, date-time

- `data` (required)
  Type: object
  
  - `message_id` (optional)
    Type: integer; nullable
    
    The id `POST /v1/my/messages` returned. Null on test events.
  
  - `to` (optional)
    Type: string
  
  - `subject` (optional)
    Type: string; nullable
  
  - `idempotency_key` (optional)
    Type: string; nullable
    
    The caller's Idempotency-Key, when one was sent.
  
  - `tags` (optional)
    Type: object
    
    The caller's delivery-option tags.
    
    Additional properties: 
      Type: string
  
  - `test` (optional)
    Type: boolean
    
    Present and true on test events.
  
  - `sent_at` (optional)
    Type: string, date-time
    
    email.sent
  
  - `bounce` (optional)
    Type: object
    
    email.bounced
    
    - `type` (optional)
      Type: string
      
      enum: ["hard","soft"]
    
    - `subtype` (optional)
      Type: string; nullable
      
      The provider's bounce subtype, e.g. NoEmail or MailboxFull.
  
  - `complaint` (optional)
    Type: object
    
    email.complained
    
    - `feedback_type` (optional)
      Type: string; nullable
      
      e.g. abuse
  
  - `url` (optional)
    Type: string
    
    email.clicked
  
  - `failure` (optional)
    Type: object
    
    email.failed
    
    - `code` (optional)
      Type: string
    
    - `reason` (optional)
      Type: string
    
    - `category` (optional)
      Type: string

## WebhookReceivedEventPayload

Type: object

Schema: [WebhookReceivedEventPayload](https://docs.nitrosend.com/api/schemas/webhookreceivedeventpayload-c69f2d8e7a.md)

- `type` (required)
  Type: string
  
  enum: ["email.received"]

- `timestamp` (required)
  Type: string, date-time
  
  When the message arrived.

- `data` (required)
  Type: object
  
  - `message_id` (optional)
    Type: integer; nullable
    
    The send this message answers, as `POST /v1/my/messages` returned it. Null when it answers none, and on test events.
  
  - `idempotency_key` (optional)
    Type: string; nullable
    
    The answered send's Idempotency-Key, when the caller sent one.
  
  - `tags` (optional)
    Type: object
    
    The answered send's delivery-option tags; empty when it answers none.
    
    Additional properties: 
      Type: string
  
  - `from` (optional)
    Type: string
  
  - `to` (optional)
    Type: string
    
    The inbox address it was sent to.
  
  - `subject` (optional)
    Type: string; nullable
  
  - `text` (optional)
    Type: string; nullable
    
    Plain-text body
  
  - `html` (optional)
    Type: string; nullable
    
    HTML body
  
  - `truncated` (optional)
    Type: boolean
    
    True when either body was cut to 64 KiB.
  
  - `auto_submitted` (optional)
    Type: boolean
    
    True for automatic replies such as out-of-office notices.
  
  - `attachments` (optional)
    Type: array
    
    Every file the message carried, in order, including files that are not available. Empty when it carried none.
    
    Items:
      Type: object
      
      - `id` (optional)
        Type: integer
      
      - `filename` (optional)
        Type: string
      
      - `content_type` (optional)
        Type: string
      
      - `size` (optional)
        Type: integer
        
        Bytes.
      
      - `scanned` (optional)
        Type: boolean
        
        True only when a virus scan found the file clean. Use `downloadable` to decide whether it can be fetched.
      
      - `scan_status` (optional)
        Type: string
        
        The file's scan verdict, as the conversations API reports it.
        
        enum: ["pending","clean","infected","failed","not_scanned"]
      
      - `downloadable` (optional)
        Type: boolean
        
        True when the conversations API will serve the file.
      
      - `download_requires_confirmation` (optional)
        Type: boolean
        
        True for a file no scan covered: fetch it with `acknowledge_unscanned=true`.
      
      - `availability_reason` (optional)
        Type: string
        
        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_omitted` (optional)
    Type: integer
    
    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.
    
    minimum: 1
  
  - `conversation_id` (optional)
    Type: integer; nullable
    
    For `GET /v1/my/conversations/{id}`. Null on test events.
  
  - `conversation_message_id` (optional)
    Type: integer; nullable
    
    Null on test events.
  
  - `test` (optional)
    Type: boolean
    
    Present and true on test events.

## CampaignCompletedWebhookData

Type: object

Schema: [CampaignCompletedWebhookData](https://docs.nitrosend.com/api/schemas/campaigncompletedwebhookdata-f644f1c7f8.md)

- `campaign_id` (required)
  Type: integer

- `campaign_name` (required)
  Type: string; nullable

- `campaign_send_id` (required)
  Type: integer; nullable

- `recipients` (required)
  Type: integer; nullable
  
  Recipients the send planned.

- `completed_at` (required)
  Type: string, date-time; nullable

## CampaignFailedWebhookData

Type: object

Schema: [CampaignFailedWebhookData](https://docs.nitrosend.com/api/schemas/campaignfailedwebhookdata-2db0ad26a5.md)

- `campaign_id` (required)
  Type: integer

- `campaign_name` (required)
  Type: string; nullable

- `campaign_send_id` (required)
  Type: integer; nullable

- `requested_recipients` (required)
  Type: integer; nullable

- `sent_count` (required)
  Type: integer; nullable

- `failure_reason` (required)
  Type: string
  
  A public reason code, e.g. campaign_delivery_failed.

- `next_action` (required)
  Type: string
  
  What to do before sending again.

## CampaignStoppedWebhookData

Type: object

Schema: [CampaignStoppedWebhookData](https://docs.nitrosend.com/api/schemas/campaignstoppedwebhookdata-39ea18c3b7.md)

- `campaign_id` (required)
  Type: integer

- `campaign_name` (required)
  Type: string; nullable

- `metric` (required)
  Type: string; nullable
  
  Bounce rate or Complaint rate.

- `rate` (required)
  Type: number; nullable
  
  The measured rate in percent.

- `threshold` (required)
  Type: number; nullable
  
  The stop threshold in percent.

- `total_sends` (required)
  Type: integer; nullable

- `hard_bounces` (required)
  Type: integer; nullable

- `complaints` (required)
  Type: integer; nullable

- `next_action` (required)
  Type: string; nullable

## FlowPausedWebhookData

Type: object

Schema: [FlowPausedWebhookData](https://docs.nitrosend.com/api/schemas/flowpausedwebhookdata-3a5ae01cf8.md)

- `flow_id` (required)
  Type: integer

- `flow_name` (required)
  Type: string; nullable

- `metric` (required)
  Type: string; nullable
  
  Bounce rate or Complaint rate.

- `rate` (required)
  Type: number; nullable
  
  The measured rate in percent.

- `threshold` (required)
  Type: number; nullable
  
  The pause threshold in percent.

## SendingPausedWebhookData

Type: object

Schema: [SendingPausedWebhookData](https://docs.nitrosend.com/api/schemas/sendingpausedwebhookdata-bff25e9f2c.md)

- `reason` (required)
  Type: string; nullable
  
  Why, e.g. critical_bounce_rate. Null when the pause is not explained.

- `sending_paused` (required)
  Type: boolean

- `occurred_at` (required)
  Type: string, date-time; nullable

## SendingLimitWebhookData

Type: object

Schema: [SendingLimitWebhookData](https://docs.nitrosend.com/api/schemas/sendinglimitwebhookdata-3e4fb49d73.md)

- `state` (required)
  Type: string
  
  enum: ["approaching","reached"]

- `label` (required)
  Type: string

- `detail` (required)
  Type: string

- `usage_percent` (required)
  Type: integer
  
  Share of the allowance used.

- `capacity` (required)
  Type: object
  
  - `limit` (required)
    Type: integer
    
    Sends allowed per window.
  
  - `remaining` (required)
    Type: integer
  
  - `window_seconds` (required)
    Type: integer
    
    The rolling window

- `retry_at` (required)
  Type: string, date-time; nullable
  
  When capacity frees up

- `upgrade_url` (required)
  Type: string; nullable
  
  Where an owner on the free plan can upgrade.

## ImportCompletedWebhookData

Type: object

Schema: [ImportCompletedWebhookData](https://docs.nitrosend.com/api/schemas/importcompletedwebhookdata-5d94768f81.md)

- `resource` (required)
  Type: string; nullable
  
  enum: ["contacts","leads",null]

- `import_id` (required)
  Type: integer

- `list_name` (required)
  Type: string; nullable

- `success_rows` (required)
  Type: integer; nullable

- `failed_rows` (required)
  Type: integer; nullable

- `total_rows` (required)
  Type: integer; nullable

## ImportFailedWebhookData

Type: object

Schema: [ImportFailedWebhookData](https://docs.nitrosend.com/api/schemas/importfailedwebhookdata-65a9de2df4.md)

- `import_id` (required)
  Type: integer; nullable

- `reason` (required)
  Type: string; nullable

- `failed_rows` (required)
  Type: integer; nullable

## DomainVerifiedWebhookData

Type: object

Schema: [DomainVerifiedWebhookData](https://docs.nitrosend.com/api/schemas/domainverifiedwebhookdata-e42de6ac20.md)

- `domain_id` (required)
  Type: integer

- `domain` (required)
  Type: string

## DomainVerificationLostWebhookData

Type: object

Schema: [DomainVerificationLostWebhookData](https://docs.nitrosend.com/api/schemas/domainverificationlostwebhookdata-63ef9c0890.md)

- `domain_id` (required)
  Type: integer

- `domain` (required)
  Type: string

- `failing` (required)
  Type: array
  
  The DNS record families that failed, e.g. dkim.
  
  Items:
    Type: string

## DomainDnsDegradedWebhookData

Type: object

Schema: [DomainDnsDegradedWebhookData](https://docs.nitrosend.com/api/schemas/domaindnsdegradedwebhookdata-f33628bf00.md)

- `domain_id` (required)
  Type: integer; nullable

- `domain` (required)
  Type: string

- `failing` (required)
  Type: array
  
  The DNS record families that failed, e.g. dkim.
  
  Items:
    Type: string

- `classification` (required)
  Type: string; nullable

- `action` (required)
  Type: string; nullable

## WebhookDisabledWebhookData

Type: object

Schema: [WebhookDisabledWebhookData](https://docs.nitrosend.com/api/schemas/webhookdisabledwebhookdata-7e3468b84c.md)

- `webhook_id` (required)
  Type: integer

- `url` (required)
  Type: string
  
  The endpoint URL without credentials or query.

- `failing_since` (required)
  Type: string, date-time; nullable

## ChatMessage

Type: object

Schema: [ChatMessage](https://docs.nitrosend.com/api/schemas/chatmessage-e51ae49d71.md)

- `id` (optional)
  Type: integer

- `role` (optional)
  Type: string
  
  enum: ["user","assistant","tool","system"]

- `content` (optional)
  Type: string
  
  Credential-shaped values are redacted before display.

- `tool_calls` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: string
    
    - `name` (optional)
      Type: string
    
    - `input` (optional)
      Type: object
      
      Additional properties: true
    
    - `safe` (optional)
      Type: boolean
    
    - `status` (optional)
      Type: string
      
      enum: ["pending","approved","executing","completed","rejected","error","cancelled","uncertain"]
    
    - `approval_token` (optional)
      Type: string
      
      Binds a proposal to its execution and exact arguments. Commands also require the originating authenticated user.
    
    - `result` (optional)
      Type: unknown
      
      Recorded tool outcome; queued does not mean sent.
    
    Additional properties: true

- `actions` (optional)
  Type: array
  
  Items:
    Type: object
    
    Additional properties: true

- `attachments` (optional)
  Type: array
  
  Images the person added to the message, from the brand's image library.
  
  Items:
    Type: object
    
    - `url` (optional)
      Type: string, uri
      
      The image's library URL.
    
    - `filename` (optional)
      Type: string
    
    - `content_type` (optional)
      Type: string
      
      enum: ["image/png","image/jpeg","image/webp"]
    
    - `width` (optional)
      Type: integer; nullable
    
    - `height` (optional)
      Type: integer; nullable

- `sequence` (optional)
  Type: integer

- `created_at` (optional)
  Type: string, date-time

## ChatSession

Type: object

Schema: [ChatSession](https://docs.nitrosend.com/api/schemas/chatsession-fadcd47090.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer

- `title` (optional)
  Type: string

- `status` (optional)
  Type: string
  
  enum: ["active","closed","failed"]

- `started_at` (optional)
  Type: string, date-time

- `last_message_at` (optional)
  Type: string, date-time

- `message_count` (optional)
  Type: integer

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## ChatSessionDetail

Type: ChatSessionDetail

Schema: [ChatSessionDetail](https://docs.nitrosend.com/api/schemas/chatsessiondetail-e50e5735ca.md)

allOf:
  Reference: [ChatSession](https://docs.nitrosend.com/api/schemas/chatsession-fadcd47090.md); Type: object

  Type: object
  
  - `messages` (optional)
    Type: array
    
    Items:
      Reference: [ChatMessage](https://docs.nitrosend.com/api/schemas/chatmessage-e51ae49d71.md); Type: object

## EmailContentFormat

Type: 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.


Schema: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md)

enum: ["designed","plain"]

## Template

Type: object

Schema: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `flow_id` (optional)
  Type: integer; nullable

- `action_id` (optional)
  Type: integer; nullable

- `version` (optional)
  Type: integer

- `subject` (optional)
  Type: string; nullable

- `body` (optional)
  Type: string; nullable

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `block_usage` (optional)
  Type: object
  
  Library templates only (flow_id null), which can be linked as blocks. What editing this template changes in the emails linking it.
  
  - `emails` (optional)
    Type: integer
    
    Emails linking it.
  
  - `publishes` (optional)
    Type: integer
    
    Emails in live or paused flows that publish the edit.
  
  - `drafts` (optional)
    Type: integer
    
    Emails in flows that get the edit in a draft for a person to publish (a change waiting to be published
  
  - `unchanged` (optional)
    Type: integer
    
    Emails that keep their content (campaigns no longer unapproved drafts

- `preheader` (optional)
  Type: string; nullable

- `from_name` (optional)
  Type: string; nullable

- `from_email` (optional)
  Type: string; nullable

- `reply_to` (optional)
  Type: string; nullable

- `design` (optional)
  Type: unknown
  
  oneOf:
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document
  
    Type: null

- `variables` (optional)
  Type: object
  
  Additional properties: true

- `generation_provenance` (optional)
  Reference: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md); Type: 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.
  

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## GenerationProvenance

Type: 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.


Schema: [GenerationProvenance](https://docs.nitrosend.com/api/schemas/generationprovenance-c92f2ca767.md)

- `state` (required)
  Type: string
  
  enum: ["candidate","accepted"]

- `event_id` (required)
  Type: integer

- `candidate_locator` (optional)
  Type: string

- `generated_slice_digest` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `acceptance_id` (optional)
  Type: integer

- `saved_authored_digest` (optional)
  Type: string
  
  pattern: "^[0-9a-f]{64}$"

- `edit_relation` (optional)
  Type: string
  
  enum: ["identical","edited"]

Additional properties: false

## EmailLibraryTemplate

Type: object

Schema: [EmailLibraryTemplate](https://docs.nitrosend.com/api/schemas/emaillibrarytemplate-2ea4251cff.md)

- `id` (optional)
  Type: string

- `name` (optional)
  Type: string

- `category` (optional)
  Type: string

- `tags` (optional)
  Type: array
  
  Items:
    Type: string

- `description` (optional)
  Type: string

- `subject` (optional)
  Type: string
  
  Suggested subject line

- `preheader` (optional)
  Type: string
  
  Suggested preheader

- `design` (optional)
  Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
  
  Email template design document

- `preview_html` (optional)
  Type: string; nullable

- `branded_design` (optional)
  Type: unknown
  
  Same layout with palette overrides stripped so brand colors apply
  
  allOf:
    Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
    
    Email template design document

- `branded_preview_html` (optional)
  Type: string; nullable

## PublicEmailCatalogTemplate

Type: object

Schema: [PublicEmailCatalogTemplate](https://docs.nitrosend.com/api/schemas/publicemailcatalogtemplate-4a9b6b54b1.md)

- `id` (required)
  Type: string

- `revision` (optional)
  Type: string
  
  Digest of the concrete public design.
  
  pattern: "^[a-f0-9]{64}$"

- `collection` (optional)
  Type: string
  
  Present for a brand concept study; originals retain their existing response shape.
  
  enum: ["brand_studies"]

- `study` (optional)
  Type: object
  
  - `brand` (required)
    Type: string
  
  - `concept` (required)
    Type: boolean
    
    enum: [true]
  
  - `adapted` (optional)
    Type: boolean
  
  - `source_url` (required)
    Type: string, uri
  
  Additional properties: false

- `name` (required)
  Type: string

- `category` (required)
  Type: string

- `tags` (required)
  Type: array
  
  Items:
    Type: string

- `description` (required)
  Type: string

- `subject` (required)
  Type: string

- `preheader` (required)
  Type: string

- `design` (required)
  Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
  
  Email template design document

Additional properties: false

## GuestFlowDemo

Type: 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.


Schema: [GuestFlowDemo](https://docs.nitrosend.com/api/schemas/guestflowdemo-b13d0caa22.md)

- `status` (required)
  Type: string
  
  enum: ["scanning","generating","ready","failed","expired"]

- `revision` (optional)
  Type: integer
  
  Advances with each brand edit or generation retry. Absent when expired.

- `domain` (optional)
  Type: string

- `goal` (optional)
  Type: string

- `brand` (optional)
  Type: object
  
  Scanned Brand Kit fields, present once the scan has completed.
  
  Additional properties: true

- `logo_url` (optional)
  Type: string
  
  Scanned logo

- `flow` (optional)
  Type: object
  
  The generated draft for the current revision, present when ready.
  
  Additional properties: true

- `failed_stage` (optional)
  Type: string
  
  Present when failed. A failed scan cannot be retried; start again.
  
  enum: ["scan","generate"]

- `message` (optional)
  Type: string
  
  Visitor copy, present when failed or expired.

- `error_code` (optional)
  Type: string
  
  Present when a generation failed on the demo's last attempt: it cannot be retried, and `message` offers an account instead.
  
  enum: ["flow_demo_attempts_exhausted"]

## TemplateSummary

Type: object

Schema: [TemplateSummary](https://docs.nitrosend.com/api/schemas/templatesummary-d07df4144e.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string; nullable

- `version` (optional)
  Type: integer

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `preview_html` (optional)
  Type: string; nullable
  
  Rendered preview, present only with ?include_previews=1

- `subject` (optional)
  Type: string; nullable

- `preheader` (optional)
  Type: string; nullable

- `flow_id` (optional)
  Type: integer; nullable

- `section_count` (optional)
  Type: integer

- `section_types` (optional)
  Type: array
  
  Items:
    Type: string

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## Flow

Type: object

Schema: [Flow](https://docs.nitrosend.com/api/schemas/flow-f1273dc72c.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `approval_state` (optional)
  Type: string

- `name` (optional)
  Type: string

- `goal` (optional)
  Type: string; nullable

- `trigger` (optional)
  Reference: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md); Type: object
  
  Trigger as returned by Flow::Format.dump

- `steps` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: object
    
    Step as returned by Flow::Format.dump

- `reply_readiness` (optional)
  Type: object; nullable
  
  Local receiving readiness for reply-enabled flows. Null when the feature is off; never provisions or calls providers.
  
  - `ready` (required)
    Type: boolean
  
  - `message` (required)
    Type: string
  
  - `retry_at` (optional)
    Type: string, date-time; nullable
  
  - `resume_plan` (optional)
    Reference: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md); Type: object
  
  - `routes` (required)
    Type: array
    
    Items:
      Type: object
      
      - `action_name` (optional)
        Type: string
      
      - `address` (optional)
        Type: string; nullable
      
      - `state` (optional)
        Type: string
      
      - `message` (optional)
        Type: string
      
      - `inbox_id` (optional)
        Type: integer
      
      - `sending_identity_id` (optional)
        Type: integer
      
      - `retry_at` (optional)
        Type: string, date-time

- `sent_count` (optional)
  Type: integer

- `engagement` (optional)
  Reference: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md); Type: Engagement

- `revenue` (optional)
  Reference: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md); Type: object
  
  Attributed revenue from the orders ledger. This block is omitted when
  the brand has no connected Shopify or Stripe revenue source.
  

- `draft_revision_id` (optional)
  Type: integer; nullable

- `draft_revision_digest` (optional)
  Type: string; nullable

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `active_revision_id` (optional)
  Type: integer; nullable

- `active_revision_digest` (optional)
  Type: string; nullable

- `has_unpublished_changes` (optional)
  Type: boolean

- `unpublished_change` (optional)
  Type: object; nullable
  
  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.
  
  
  - `revision_id` (required)
    Type: integer
  
  - `saved_at` (required)
    Type: string, date-time
  
  - `blockers` (optional)
    Type: array
    
    Items:
      Type: object
      
      - `check` (required)
        Type: string
      
      - `message` (required)
        Type: string
      
      - `how_to_fix` (optional)
        Type: string
      
      - `recovery_actions` (optional)
        Type: array
        
        Items:
          Reference: [SafetyRecoveryAction](https://docs.nitrosend.com/api/schemas/safetyrecoveryaction-c546cd555d.md); Type: object
      
      - `agent_prompt` (optional)
        Type: string
        
        Each held email's fix to paste to an agent, joined.
      
      - `disclosures` (optional)
        Type: array
        
        Each held flow email and its case.
        
        Items:
          Type: object
          
          - `action` (optional)
            Type: string
          
          - `review_id` (optional)
            Type: integer
          
          - `category` (optional)
            Type: string
          
          - `agent_prompt` (optional)
            Type: string

- `saves_publish` (optional)
  Type: boolean
  
  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_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

- `templates` (optional)
  Type: array
  
  Items:
    Reference: [Template](https://docs.nitrosend.com/api/schemas/template-0575f29df8.md); Type: object

## FlowResumePlan

Type: object

Schema: [FlowResumePlan](https://docs.nitrosend.com/api/schemas/flowresumeplan-0a9b107bd8.md)

- `flow_id` (required)
  Type: integer

- `status` (required)
  Type: string
  
  enum: ["draft","live","paused","archived","cancelled"]

- `open_journey_count` (required)
  Type: integer
  
  minimum: 0

- `contact_count` (required)
  Type: integer
  
  minimum: 0

- `waiting_journey_count` (required)
  Type: integer
  
  minimum: 0

- `scheduled_journey_count` (required)
  Type: integer
  
  minimum: 0

- `has_unpublished_changes` (required)
  Type: boolean

- `draft_approval_state` (optional)
  Type: string; nullable
  
  enum: ["pending_review","approved","rejected"]

- `requires_choice` (required)
  Type: boolean

- `allowed_modes` (required)
  Type: array
  
  Items:
    Type: string
    
    enum: ["new_contacts_only","continue_existing"]

- `recommended_mode` (required)
  Type: string
  
  enum: ["new_contacts_only"]

## FlowTemplate

Type: object

Lean flow template card for index listings.

Schema: [FlowTemplate](https://docs.nitrosend.com/api/schemas/flowtemplate-f707a80e4c.md)

- `id` (optional)
  Type: string
  
  Template slug (e.g. `welcome`)

- `type_label` (optional)
  Type: string

- `description` (optional)
  Type: string

- `category` (optional)
  Type: string

- `icon` (optional)
  Type: string
  
  Font Awesome icon name for the template's card, without the `fa-` prefix.

- `needs_list` (optional)
  Type: boolean
  
  Whether creating it takes `trigger.contact_list_id`, the brand list it starts on.

- `brand_writable` (optional)
  Type: boolean
  
  Whether POST /v1/my/flows/generate can write this template for the brand.

- `email_count` (optional)
  Type: integer

- `step_count` (optional)
  Type: integer

## FlowTemplateDetail

Type: FlowTemplateDetail

Schema: [FlowTemplateDetail](https://docs.nitrosend.com/api/schemas/flowtemplatedetail-7a33615694.md)

allOf:
  Reference: [FlowTemplate](https://docs.nitrosend.com/api/schemas/flowtemplate-f707a80e4c.md); Type: object
  
  Lean flow template card for index listings.

  Type: object
  
  Full flow template including the graph, ready for POST /v1/my/flows.
  
  - `trigger` (optional)
    Type: object
    
    Trigger definition (pass as-is to POST /v1/my/flows trigger param)
    
    Additional properties: true
  
  - `steps` (optional)
    Type: array
    
    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`.
    
    
    Items:
      Type: object
      
      Additional properties: true

## EngagementBucket

Type: 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.


Schema: [EngagementBucket](https://docs.nitrosend.com/api/schemas/engagementbucket-3122bcf7f5.md)

- `sent` (required)
  Type: integer
  
  Emails the provider accepted in this bucket (test sends excluded).

- `delivered` (required)
  Type: integer
  
  Provider-confirmed deliveries, excluding final bounces. Missing feedback is not delivery confirmation.

- `non_bounced` (optional)
  Type: integer
  
  Accepted emails minus known bounces; the denominator of open and click rates.

- `unconfirmed` (optional)
  Type: integer
  
  Accepted emails without a confirmed delivery or final bounce. Never treat these as bounces or retry sends from this count.

- `opens` (required)
  Type: integer
  
  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_opens` (required)
  Type: integer
  
  All counted open observations of non-bounced emails, including repeat opens, so
  `total_opens >= opens`. A volume figure, never a rate numerator.
  

- `open_rate` (required)
  Type: number, float; nullable
  
  `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

Type: Engagement

Schema: [Engagement](https://docs.nitrosend.com/api/schemas/engagement-ea68771a39.md)

allOf:
  Reference: [EngagementBucket](https://docs.nitrosend.com/api/schemas/engagementbucket-3122bcf7f5.md); Type: 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.
  

  Type: object
  
  - `account` (required)
    Reference: [EngagementBucket](https://docs.nitrosend.com/api/schemas/engagementbucket-3122bcf7f5.md); Type: 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.
    

## EngagementCohortBucket

Type: 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.


Schema: [EngagementCohortBucket](https://docs.nitrosend.com/api/schemas/engagementcohortbucket-2ec5f71891.md)

- `sent` (required)
  Type: integer
  
  Emails the provider accepted.

- `delivered` (required)
  Type: integer
  
  Provider-confirmed deliveries excluding final bounces.

- `non_bounced` (optional)
  Type: integer
  
  `sent - bounced`; the open and click rate denominator.

- `unconfirmed` (optional)
  Type: integer
  
  `sent - bounced - delivered`; missing feedback is neither a confirmed delivery nor a bounce.

- `bounced` (required)
  Type: integer
  
  Emails that bounced.

- `opens` (required)
  Type: integer
  
  Non-bounced emails opened at least once. Known scanners excluded; automatic privacy image loads can count. Not proof of human readership.

- `total_opens` (required)
  Type: integer
  
  Counted open observations including repeats; never a rate numerator.

- `clicks` (required)
  Type: integer
  
  Non-bounced emails clicked at least once; `clicks <= non_bounced`.

- `total_clicks` (required)
  Type: integer
  
  Counted click observations of non-bounced emails.

- `forwards` (required)
  Type: integer
  
  Non-bounced emails with a recorded forward.

- `delivered_rate` (required)
  Type: number, float; nullable
  
  `delivered / sent`.

- `open_rate` (required)
  Type: number, float; nullable
  
  `opens / non_bounced`.

- `click_rate` (required)
  Type: number, float; nullable
  
  `clicks / non_bounced`.

- `bounce_rate` (required)
  Type: number, float; nullable
  
  `bounced / sent`.

## MessageSendsEngagement

Type: object

Schema: [MessageSendsEngagement](https://docs.nitrosend.com/api/schemas/messagesendsengagement-5bdc200a80.md)

- `interval` (required)
  Type: string
  
  Series bucket size (`hour` for today, `month` for all time, otherwise `day`).
  
  enum: ["hour","day","month"]

- `summary` (required)
  Reference: [EngagementCohortBucket](https://docs.nitrosend.com/api/schemas/engagementcohortbucket-2ec5f71891.md); Type: 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.
  

- `series` (required)
  Type: array
  
  One entry per interval of the window (zero-filled), plus any later interval with sends; entries add up to `summary`.
  
  
  Items:
    Type: unknown
    
    allOf:
      Type: object
      
      - `bucket_start` (required)
        Type: string, date-time
    
      Reference: [EngagementCohortBucket](https://docs.nitrosend.com/api/schemas/engagementcohortbucket-2ec5f71891.md); Type: 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.
      

- `has_sends` (required)
  Type: boolean
  
  Whether the source has ever accepted a non-test email (outside the window too).

## MessageSendsRow

Type: object

Schema: [MessageSendsRow](https://docs.nitrosend.com/api/schemas/messagesendsrow-d842990b20.md)

- `source_type` (required)
  Type: string
  
  enum: ["campaign","flow","transactional","test"]

- `row_key` (required)
  Type: string

- `source_id` (optional)
  Type: integer; nullable
  
  Campaign or flow id; null for transactional and test rows.

- `source_name` (required)
  Type: string

- `date` (optional)
  Type: string, date; nullable
  
  Creation day of a transactional or test row.

- `subject` (optional)
  Type: string; nullable

- `recipients` (optional)
  Type: string; nullable

- `recipients_count` (optional)
  Type: integer

- `total` (required)
  Type: integer
  
  Messages in the row (every status and channel) within the window.

- `sent` (required)
  Type: integer
  
  Messages of the row the provider accepted (every channel).

- `failed` (required)
  Type: integer

- `queued` (required)
  Type: integer

- `latest_failure_code` (optional)
  Type: string; nullable

- `latest_failure_reason` (optional)
  Type: string; nullable

- `latest_failure_category` (optional)
  Type: string; nullable

- `last_sent_at` (optional)
  Type: string, date-time; nullable

- `delivered` (required)
  Type: integer
  
  The row's provider-confirmed deliveries (0 on test and failed-only rows).

- `non_bounced` (optional)
  Type: integer
  
  Accepted non-test emails minus known bounces.

- `unconfirmed` (optional)
  Type: integer
  
  Accepted non-test emails without a final provider outcome.

- `opened` (required)
  Type: integer
  
  Non-bounced emails of the row opened at least once; privacy image loads can count.

- `clicked` (required)
  Type: integer
  
  Non-bounced emails of the row clicked at least once.

- `open_rate` (required)
  Type: number
  
  Percentage (0-100, 1 dp) of `non_bounced`; 0 without a denominator.

- `click_rate` (required)
  Type: number
  
  Percentage (0-100, 1 dp) of `non_bounced`; 0 without a denominator.

- `delivery` (optional)
  Type: object
  
  Send progress of a campaign row with an active send (same projection as the campaign delivery endpoints).
  
  Additional properties: true

## MessageSendsCounts

Type: object

Message counts for the filter pills, over the same window as the rows.

Schema: [MessageSendsCounts](https://docs.nitrosend.com/api/schemas/messagesendscounts-007f057fc0.md)

- `all` (required)
  Type: integer
  
  Messages of every source in the `since` window (with `failed`).

- `campaign` (required)
  Type: integer

- `flow` (required)
  Type: integer

- `transactional` (required)
  Type: integer

- `test` (required)
  Type: integer

- `time` (required)
  Type: object
  
  Messages of the selected source (with `failed`) per window.
  
  - `all` (required)
    Type: integer
  
  - `today` (required)
    Type: integer
  
  - `7d` (required)
    Type: integer
  
  - `30d` (required)
    Type: integer
  
  - `3m` (required)
    Type: integer

## MessageSendsResponse

Type: object

Schema: [MessageSendsResponse](https://docs.nitrosend.com/api/schemas/messagesendsresponse-88a9a1f9af.md)

- `rows` (required)
  Type: array
  
  Items:
    Reference: [MessageSendsRow](https://docs.nitrosend.com/api/schemas/messagesendsrow-d842990b20.md); Type: object

- `counts` (required)
  Reference: [MessageSendsCounts](https://docs.nitrosend.com/api/schemas/messagesendscounts-007f057fc0.md); Type: object
  
  Message counts for the filter pills, over the same window as the rows.

- `engagement` (required)
  Reference: [MessageSendsEngagement](https://docs.nitrosend.com/api/schemas/messagesendsengagement-5bdc200a80.md); Type: object

## RevenueMessageBreakdown

Type: object

Schema: [RevenueMessageBreakdown](https://docs.nitrosend.com/api/schemas/revenuemessagebreakdown-be28698c10.md)

- `message_id` (optional)
  Type: integer

- `subject` (optional)
  Type: string; nullable

- `sent_at` (optional)
  Type: string, date-time; nullable

- `currency` (optional)
  Type: string; nullable
  
  Dominant attributed order currency for this message row.

- `mixed_currency` (optional)
  Type: boolean
  
  True when attributed orders included more than one currency before dominant-currency filtering.

- `delivered` (optional)
  Type: integer

- `attributed_orders` (optional)
  Type: integer

- `attributed_revenue_cents` (optional)
  Type: integer
  
  Net attributed revenue in cents from the orders ledger.

- `revenue_per_recipient` (optional)
  Type: number, float; nullable

- `conversion_rate` (optional)
  Type: number, float; nullable

- `attributed_aov` (optional)
  Type: number, float; nullable

## RevenueReport

Type: object

Attributed revenue from the orders ledger. This block is omitted when
the brand has no connected Shopify or Stripe revenue source.


Schema: [RevenueReport](https://docs.nitrosend.com/api/schemas/revenuereport-74d21965ff.md)

- `attribution_label` (optional)
  Type: string
  
  Example:
  
  ```json
  "Attributed revenue. Last click, 7-day window."
  ```

- `currency` (optional)
  Type: string; nullable
  
  Dominant attributed order currency used for revenue math. Null when no attributed orders carry a currency.

- `mixed_currency` (optional)
  Type: boolean
  
  True when attributed orders included more than one currency before dominant-currency filtering.

- `attributed_revenue_cents` (optional)
  Type: integer
  
  Net attributed revenue in cents from the orders ledger.

- `delivered` (optional)
  Type: integer

- `attributed_orders` (optional)
  Type: integer

- `revenue_per_recipient` (optional)
  Type: number, float; nullable
  
  Net attributed revenue in major currency units divided by delivered recipients.

- `conversion_rate` (optional)
  Type: number, float; nullable
  
  Attributed paid orders divided by delivered recipients.

- `attributed_aov` (optional)
  Type: number, float; nullable
  
  Net attributed revenue in major currency units divided by attributed paid orders.

- `message_breakdown` (optional)
  Type: array
  
  Items:
    Reference: [RevenueMessageBreakdown](https://docs.nitrosend.com/api/schemas/revenuemessagebreakdown-be28698c10.md); Type: object

## ProfileEnrichmentAudience

Type: object

Exactly one same-Brand selection. Existing identity and profile ownership are preserved.

Schema: [ProfileEnrichmentAudience](https://docs.nitrosend.com/api/schemas/profileenrichmentaudience-4408908270.md)

- `contact_ids` (optional)
  Type: array
  
  minItems: 1
  
  maxItems: 100
  
  uniqueItems: true
  
  Items:
    Type: integer

oneOf:
  Type: unknown
  
  Must not match:
    Type: unknown

## FlowTrigger

Type: object

Schema: [FlowTrigger](https://docs.nitrosend.com/api/schemas/flowtrigger-a0c6b5a022.md)

- `id` (optional)
  Type: integer

- `flow_id` (optional)
  Type: integer

- `event` (optional)
  Type: string

- `audience_type` (optional)
  Type: string; nullable
  
  Explicit campaign audience target; null means no audience selected.
  
  enum: ["lists","segment","all_contacts"]

- `segment_id` (optional)
  Type: integer; nullable

- `contact_list_id` (optional)
  Type: integer; nullable
  
  Deprecated — use contact_list_ids
  
  deprecated: true

- `contact_list_ids` (optional)
  Type: array
  
  Contact list IDs targeted by this trigger
  
  Items:
    Type: integer

- `exclude_segment_ids` (optional)
  Type: array
  
  Segment IDs whose matching contacts are excluded from the recipient set
  
  Items:
    Type: integer

- `exclude_contact_list_ids` (optional)
  Type: array
  
  Contact list IDs whose members are excluded from the recipient set
  
  Items:
    Type: integer

- `data` (optional)
  Type: object; nullable
  
  Additional properties: true

- `triggered_count` (optional)
  Type: integer

- `last_triggered_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## FlowTriggerInput

Type: object

Schema: [FlowTriggerInput](https://docs.nitrosend.com/api/schemas/flowtriggerinput-730691eb66.md)

- `stop_on_reply` (optional)
  Type: boolean
  
  Stop only the enrollment whose tracked email received a proven human reply. Requires monitored receiving.
  
  default: false

- `reply_source` (optional)
  Reference: [ReplySource](https://docs.nitrosend.com/api/schemas/replysource-243ea0e0a1.md); Type: ReplySource

- `exit_events` (optional)
  Type: array
  
  New same-brand/contact events after journey entry stop future steps. Pinned in the approved revision; cannot recall a step already executing.
  
  maxItems: 20
  
  Items:
    Type: string
    
    pattern: "^[a-z][a-z0-9_]{0,63}$"

- `event` (optional)
  Type: string
  
  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_type` (optional)
  Type: string; nullable
  
  Explicit campaign audience target; null means no audience selected.
  
  enum: ["lists","segment","all_contacts"]

- `segment_id` (optional)
  Type: integer; nullable

- `contact_list_id` (optional)
  Type: integer; nullable
  
  Deprecated — use contact_list_ids
  
  deprecated: true

- `contact_list_ids` (optional)
  Type: array
  
  Contact list IDs to target
  
  Items:
    Type: integer

- `exclude_segment_ids` (optional)
  Type: array
  
  Segment IDs whose matching contacts are excluded from the recipient set; pass [] to clear
  
  Items:
    Type: integer

- `data` (optional)
  Type: object
  
  Additional properties: true

## FlowTriggerOutput

Type: object

Trigger as returned by Flow::Format.dump

Schema: [FlowTriggerOutput](https://docs.nitrosend.com/api/schemas/flowtriggeroutput-ea9046edac.md)

- `stop_on_reply` (optional)
  Type: boolean

- `reply_source` (optional)
  Reference: [ReplySource](https://docs.nitrosend.com/api/schemas/replysource-243ea0e0a1.md); Type: ReplySource

- `exit_events` (optional)
  Type: array
  
  Items:
    Type: string

- `event` (optional)
  Type: string

- `segment_id` (optional)
  Type: integer; nullable

- `contact_list_id` (optional)
  Type: integer; nullable

- `exclude_segment_ids` (optional)
  Type: array
  
  Segment IDs whose matching contacts are excluded from the recipient set
  
  Items:
    Type: integer

- `data` (optional)
  Type: object; nullable
  
  Additional properties: true

## FlowStepInput

Type: object

Schema: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md)

- `type` (required)
  Type: string
  
  enum: ["email","sms","wait","split","classify_reply","reply","emit_event","webhook","subscribe","unsubscribe"]

- `categories` (optional)
  Type: array
  
  minItems: 2
  
  maxItems: 6
  
  Items:
    Reference: [ReplyCategory](https://docs.nitrosend.com/api/schemas/replycategory-1039597caa.md); Type: object

- `branches` (optional)
  Type: object
  
  Every declared category key and other must have an explicit path. A branch node ends its sequence.
  
  Additional properties: 
    Type: array
    
    Items:
      Reference: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md); Type: FlowStepInput

- `reply_all` (optional)
  Type: boolean
  
  default: false

- `cc` (optional)
  Type: array
  
  Items:
    Type: string, email

- `bcc` (optional)
  Type: array
  
  Items:
    Type: string, email

- `subject` (optional)
  Type: string
  
  Email step: subject line

- `body` (optional)
  Type: string
  
  SMS body or email plain text

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: 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.
  
  
  enum: ["designed","plain"]

- `plain_text_mode` (optional)
  Type: string
  
  enum: ["derived","custom"]

- `preheader` (optional)
  Type: string
  
  Email step: preheader

- `from_name` (optional)
  Type: string

- `from_email` (optional)
  Type: string

- `reply_to` (optional)
  Type: string

- `design` (optional)
  Reference: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md); Type: object
  
  Email template design document

- `duration` (optional)
  Type: integer
  
  Wait step: seconds, positive unless send_at is configured
  
  minimum: 0

- `send_at` (optional)
  Type: string
  
  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.
  
  pattern: "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"

- `time_zone` (optional)
  Type: string
  
  IANA time zone for send_at. Defaults from the account owner or Etc/UTC and is pinned in the approved runtime.

- `filters` (optional)
  Reference: [SegmentFilterExpression](https://docs.nitrosend.com/api/schemas/segmentfilterexpression-2363b1f879.md); Type: SegmentFilterExpression
  
  Split step: condition filters

- `yes` (optional)
  Type: array
  
  Split step: yes branch
  
  Items:
    Reference: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md); Type: FlowStepInput

- `no` (optional)
  Type: array
  
  Split step: no branch
  
  Items:
    Reference: [FlowStepInput](https://docs.nitrosend.com/api/schemas/flowstepinput-f0371438af.md); Type: FlowStepInput

- `event_name` (optional)
  Type: string
  
  Emit event step: event to fire

- `forward_event_data` (optional)
  Type: boolean
  
  default: false

- `event_data` (optional)
  Type: object
  
  Additional properties: true

- `transactional` (optional)
  Type: boolean
  
  default: false

## FlowStepOutput

Type: object

Step as returned by Flow::Format.dump

Schema: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md)

- `type` (optional)
  Type: string
  
  enum: ["email","sms","wait","split","classify_reply","reply","emit_event","webhook","subscribe","unsubscribe"]

- `categories` (optional)
  Type: array
  
  Items:
    Reference: [ReplyCategory](https://docs.nitrosend.com/api/schemas/replycategory-1039597caa.md); Type: object

- `branches` (optional)
  Type: object
  
  Additional properties: 
    Type: array
    
    Items:
      Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: FlowStepOutput

- `reply_all` (optional)
  Type: boolean

- `cc` (optional)
  Type: array
  
  Items:
    Type: string, email

- `bcc` (optional)
  Type: array
  
  Items:
    Type: string, email

- `subject` (optional)
  Type: string

- `body` (optional)
  Type: string

- `content_format` (optional)
  Reference: [EmailContentFormat](https://docs.nitrosend.com/api/schemas/emailcontentformat-5ac5897d53.md); Type: string
  
  Persisted presentation for an email step; defaults to designed.
  
  enum: ["designed","plain"]

- `preheader` (optional)
  Type: string

- `duration` (optional)
  Type: integer

- `send_at` (optional)
  Type: string

- `time_zone` (optional)
  Type: string

- `filters` (optional)
  Type: array
  
  Items:
    Type: object

- `yes` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: FlowStepOutput

- `no` (optional)
  Type: array
  
  Items:
    Reference: [FlowStepOutput](https://docs.nitrosend.com/api/schemas/flowstepoutput-c15400e350.md); Type: FlowStepOutput

- `event_name` (optional)
  Type: string

- `forward_event_data` (optional)
  Type: boolean

## ReplySource

Type: ReplySource

Schema: [ReplySource](https://docs.nitrosend.com/api/schemas/replysource-243ea0e0a1.md)

oneOf:
  Type: object
  
  - `type` (required)
    Type: string
    
    enum: ["any"]
  
  Additional properties: false

  Type: object
  
  - `type` (required)
    Type: string
    
    enum: ["flow","campaign","message"]
  
  - `id` (required)
    Type: integer
    
    Existing resource in the same brand.
    
    minimum: 1
  
  Additional properties: false

## ReplyCategory

Type: object

Schema: [ReplyCategory](https://docs.nitrosend.com/api/schemas/replycategory-1039597caa.md)

- `key` (required)
  Type: string
  
  Stable branch key; other is reserved.
  
  pattern: "^[a-z][a-z0-9_]{0,39}$"

- `label` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 60

- `description` (required)
  Type: string
  
  minLength: 1
  
  maxLength: 500

Additional properties: false

## Event

Type: object

Schema: [Event](https://docs.nitrosend.com/api/schemas/event-4e1f49a9c8.md)

- `id` (optional)
  Type: integer

- `account_id` (optional)
  Type: integer

- `contact_id` (optional)
  Type: integer

- `user_id` (optional)
  Type: integer

- `event` (optional)
  Type: string

- `amount` (optional)
  Type: number, double; nullable

- `data` (optional)
  Type: object
  
  Additional properties: true

- `idempotency_key` (optional)
  Type: string; nullable

- `resource_uid` (optional)
  Type: string; nullable

- `resource_name` (optional)
  Type: string; nullable

- `resource_url` (optional)
  Type: string; nullable

- `test` (optional)
  Type: boolean

- `generated` (optional)
  Type: boolean

- `chain_depth` (optional)
  Type: integer

- `ip` (optional)
  Type: string; nullable

- `user_agent` (optional)
  Type: string; nullable

- `browser` (optional)
  Type: string; nullable

- `os` (optional)
  Type: string; nullable

- `device_type` (optional)
  Type: string; nullable

- `referrer` (optional)
  Type: string; nullable

- `utm_source` (optional)
  Type: string; nullable

- `utm_medium` (optional)
  Type: string; nullable

- `utm_term` (optional)
  Type: string; nullable

- `utm_content` (optional)
  Type: string; nullable

- `utm_campaign` (optional)
  Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## SharedSubdomain

Type: object

Schema: [SharedSubdomain](https://docs.nitrosend.com/api/schemas/sharedsubdomain-a7e22f14b2.md)

- `id` (required)
  Type: integer

- `name` (required)
  Type: string
  
  The recipient's visible From domain.

- `sending_domain_id` (required)
  Type: integer

- `sending_domain_name` (required)
  Type: string

- `account_id` (required)
  Type: integer

- `account_name` (required)
  Type: string

- `brand_id` (required)
  Type: integer

- `brand_sid` (required)
  Type: string

- `brand_name` (required)
  Type: string

- `active` (required)
  Type: boolean
  
  Domain permission is current; DNS verification remains a separate requirement.

- `revoked_at` (optional)
  Type: string, date-time; nullable

- `dns_verified` (required)
  Type: boolean

## SubdomainSharingSummary

Type: object

Schema: [SubdomainSharingSummary](https://docs.nitrosend.com/api/schemas/subdomainsharingsummary-18129033e5.md)

- `parent` (required)
  Type: object
  
  - `id` (optional)
    Type: integer
  
  - `name` (optional)
    Type: string

- `destinations` (required)
  Type: array
  
  maxItems: 100
  
  Items:
    Type: object
    
    - `account_id` (optional)
      Type: integer
    
    - `account_name` (optional)
      Type: string
    
    - `brand_id` (optional)
      Type: integer
    
    - `brand_sid` (optional)
      Type: string
    
    - `brand_name` (optional)
      Type: string

- `destinations_truncated` (required)
  Type: boolean

- `subdomains` (required)
  Type: array
  
  maxItems: 25
  
  Items:
    Reference: [SharedSubdomain](https://docs.nitrosend.com/api/schemas/sharedsubdomain-a7e22f14b2.md); Type: object

- `pagination` (required)
  Type: object
  
  - `page` (optional)
    Type: integer
  
  - `total_pages` (optional)
    Type: integer
  
  - `total_count` (optional)
    Type: integer

## Domain

Type: object

Schema: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md)

- `id` (optional)
  Type: integer

- `brand_id` (optional)
  Type: integer; nullable

- `name` (optional)
  Type: string

- `provider` (optional)
  Type: string
  
  default: "ses"

- `default_from_domain` (optional)
  Type: string
  
  Domain Nitrosend will use for visible From addresses when this sending domain is selected.

- `subdomain_sharing_available` (optional)
  Type: boolean
  
  The current principal can manage sharing on this verified apex.

- `shared_subdomain` (optional)
  Type: object
  
  Present only for a shared child, including after permission ends. DNS status is independent.
  
  - `active` (optional)
    Type: boolean
  
  - `parent_domain` (optional)
    Type: string; nullable
  
  - `message` (optional)
    Type: string; nullable

- `sender_authorization_reason` (optional)
  Type: string
  
  Machine-readable reason the default visible From domain is or is not authorized.
  
  enum: ["missing_sender_domain","exact_inbox","exact_mailbox","shared_domain_requires_exact_inbox","shared_domain_not_verified","platform_domain","sender_domain_not_authorized","sending_domain","unaligned_apex_supported","author_identity_not_verified","author_domain_unaligned","author_domain","sender_domain_mismatch"]

- `outstanding` (optional)
  Type: object; nullable
  
  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.
  
  - `code` (required)
    Type: string
    
    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.
    
    enum: ["dns_records","provider_confirmation","domain_review","domain_permission"]
  
  - `action_required` (required)
    Type: boolean
    
    True when the customer has to act; false when the domain verifies on its own.
  
  - `items` (required)
    Type: array
    
    The DNS records or provider checks still outstanding, per domain.
    
    Items:
      Type: object
      
      - `domain` (required)
        Type: string
        
        The sending domain or its From domain.
      
      - `check` (required)
        Type: string
        
        A DNS family (verification, spf, dkim, dmarc, mx, return_path, tracking) for dns_records, or a provider check (verification, dkim, mail_from, tenant_association).
  
  - `message` (required)
    Type: string
    
    Customer-facing explanation
  
  - `next_check_at` (required)
    Type: string, date-time; nullable
    
    When Nitrosend next checks this domain automatically; null when nothing is scheduled.

- `integration_id` (optional)
  Type: integer; nullable

- `status` (optional)
  Type: string
  
  enum: ["pending","verified"]

- `dmarc_policy` (optional)
  Type: string
  
  Effective observed DMARC policy persisted by Nitrosend; defaults to none until observed.
  
  enum: ["none","quarantine","reject"]

- `dmarc_recommended_policy` (optional)
  Type: string
  
  Nitrosend's recommended DMARC policy rung.
  
  enum: ["none","quarantine","reject"]

- `dmarc_observed_policy` (optional)
  Type: string; nullable
  
  Last live DMARC policy observed by Nitrosend.
  
  enum: ["none","quarantine","reject"]

- `dns_records` (optional)
  Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object; nullable

- `inbound_setup` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md); Type: object

- `dns_health` (optional)
  Type: object; nullable
  
  Additional properties: true

- `dns_setup_status` (optional)
  Type: string
  
  enum: ["unchecked","incomplete","ready","verified"]

- `verified_at` (optional)
  Type: string, date-time; nullable

- `created_at` (optional)
  Type: string, date-time

## EntriSessionResponse

Type: object

Schema: [EntriSessionResponse](https://docs.nitrosend.com/api/schemas/entrisessionresponse-28835b7ca8.md)

- `domain` (required)
  Reference: [Domain](https://docs.nitrosend.com/api/schemas/domain-79fa33618d.md); Type: object

- `entri` (required)
  Type: object
  
  - `application_id` (required)
    Type: string
  
  - `token` (required)
    Type: string
  
  - `prefilled_domain` (required)
    Type: string
  
  - `user_id` (required)
    Type: string
  
  - `dns_records` (required)
    Type: array
    
    Items:
      Reference: [EntriDnsRecord](https://docs.nitrosend.com/api/schemas/entridnsrecord-a42a1598c4.md); Type: object
  
  - `manual_dns_records` (required)
    Reference: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md); Type: object

## EntriSessionRequest

Type: object

Schema: [EntriSessionRequest](https://docs.nitrosend.com/api/schemas/entrisessionrequest-3578743add.md)

- `apex_mx_override` (optional)
  Type: boolean
  
  Explicitly include the prepared company-inbox MX cutover in this session.
  
  default: false

- `apex_mx_confirmation` (optional)
  Type: string
  
  Exact apex domain name being approved. Required when apex_mx_override is true.

## EntriSessionValidationError

Type: EntriSessionValidationError

Schema: [EntriSessionValidationError](https://docs.nitrosend.com/api/schemas/entrisessionvalidationerror-b75a934a6b.md)

allOf:
  Reference: [Error](https://docs.nitrosend.com/api/schemas/error-54a0e8c17e.md); Type: object

  Type: object
  
  - `blockers` (optional)
    Type: array
    
    Machine-readable reasons the apex MX cutover cannot proceed.
    
    Items:
      Type: string

## DomainDnsRecords

Type: object

Schema: [DomainDnsRecords](https://docs.nitrosend.com/api/schemas/domaindnsrecords-3f51a93e16.md)

- `sending_dns_records` (optional)
  Type: array
  
  Items:
    Reference: [DomainDnsRecord](https://docs.nitrosend.com/api/schemas/domaindnsrecord-e953e979a6.md); Type: object

- `receiving_dns_records` (optional)
  Type: array
  
  Items:
    Reference: [DomainDnsRecord](https://docs.nitrosend.com/api/schemas/domaindnsrecord-e953e979a6.md); Type: object

Additional properties: true

## DomainDnsRecord

Type: object

Schema: [DomainDnsRecord](https://docs.nitrosend.com/api/schemas/domaindnsrecord-e953e979a6.md)

- `record_type` (optional)
  Type: string

- `name` (optional)
  Type: string

- `relative_name` (optional)
  Type: string
  
  Record name relative to the registrable domain, as most registrars' Host field expects; `@` for the apex.

- `value` (optional)
  Type: string

- `priority` (optional)
  Type: string; nullable

- `valid` (optional)
  Type: string; nullable

- `purpose` (optional)
  Type: string; nullable

- `required` (optional)
  Type: boolean; nullable

- `mail_forwarding` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainMailForwarding](https://docs.nitrosend.com/api/schemas/domainmailforwarding-10ad60b6a8.md); Type: object

## DomainMailForwarding

Type: object

Schema: [DomainMailForwarding](https://docs.nitrosend.com/api/schemas/domainmailforwarding-10ad60b6a8.md)

- `enabled` (required)
  Type: boolean

- `route_type` (required)
  Type: string
  
  enum: ["legacy_forward_all","unmatched_forward"]

- `destination_type` (required)
  Type: string
  
  enum: ["legacy_mx","smtp_relay"]

- `legacy_mx_records` (required)
  Type: array
  
  Items:
    Reference: [MxRecord](https://docs.nitrosend.com/api/schemas/mxrecord-ddfac5fe43.md); Type: object

- `setup_note` (required)
  Type: string

## DomainInboundSetupRequest

Type: object

Schema: [DomainInboundSetupRequest](https://docs.nitrosend.com/api/schemas/domaininboundsetuprequest-41f610fba4.md)

- `inbound_setup` (required)
  Type: object
  
  - `method` (required)
    Type: string
    
    enum: ["provider_forwarding","mx"]
  
  - `provider` (optional)
    Type: string
    
    Required when method is provider_forwarding.
    
    enum: ["google_workspace","microsoft_365","zoho","other"]
  
  - `local_part` (optional)
    Type: string
    
    Select an exact existing address, or request creation subject to the current inbox allowance.
  
  - `inbox_id` (optional)
    Type: integer
    
    Existing inbox on this domain. Required for an ambiguous setup when local_part is omitted.
  
  - `display_name` (optional)
    Type: string; nullable
  
  - `prepare` (optional)
    Type: boolean
    
    Prepare apex receiving before opening the existing Entri MX connection. Does not change DNS.
    
    default: false
  
  - `no_existing_mail_service` (optional)
    Type: boolean
    
    Explicit first-mailbox choice. Rejected when public MX or a saved route identifies an existing mail service.
    
    default: false
  
  Additional properties: false

Additional properties: false

## DomainInboundSetup

Type: object

Schema: [DomainInboundSetup](https://docs.nitrosend.com/api/schemas/domaininboundsetup-ead135fd6c.md)

- `method` (required)
  Type: string
  
  enum: ["none","provider_forwarding","mx"]

- `status` (required)
  Type: string
  
  enum: ["not_configured","pending","active","attention"]

- `requires_inbox_selection` (optional)
  Type: boolean
  
  Several inboxes exist and no specific inbox was selected.

- `mx_scope` (optional)
  Type: string; nullable
  
  enum: ["apex","subdomain"]

- `inbox` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainInboundInbox](https://docs.nitrosend.com/api/schemas/domaininboundinbox-a6f724481c.md); Type: object

- `provider_forwarding` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainProviderForwarding](https://docs.nitrosend.com/api/schemas/domainproviderforwarding-e2424ad080.md); Type: object

- `apex_mx` (optional)
  Type: unknown; nullable
  
  allOf:
    Reference: [DomainApexMxSetup](https://docs.nitrosend.com/api/schemas/domainapexmxsetup-fede889967.md); Type: object

## DomainInboundInbox

Type: object

Schema: [DomainInboundInbox](https://docs.nitrosend.com/api/schemas/domaininboundinbox-a6f724481c.md)

- `id` (required)
  Type: integer

- `address` (required)
  Type: string, email

- `display_name` (optional)
  Type: string; nullable
  
  maxLength: 255

- `status` (required)
  Type: string
  
  enum: ["active","disabled","archived"]

## DomainProviderForwarding

Type: object

Schema: [DomainProviderForwarding](https://docs.nitrosend.com/api/schemas/domainproviderforwarding-e2424ad080.md)

- `provider` (required)
  Type: string
  
  enum: ["google_workspace","microsoft_365","zoho","other"]

- `forwarding_address` (required)
  Type: string, email
  
  readOnly: true

- `probe_sent_at` (optional)
  Type: string, date-time; nullable

- `verified_at` (optional)
  Type: string, date-time; nullable

## DomainApexMxSetup

Type: object

Schema: [DomainApexMxSetup](https://docs.nitrosend.com/api/schemas/domainapexmxsetup-fede889967.md)

- `mode` (optional)
  Type: string
  
  enum: ["standalone","forward_all"]

- `preparation` (optional)
  Type: object
  
  - `state` (optional)
    Type: string
    
    enum: ["queued","preparing","probing","ready","failed"]
  
  - `message` (optional)
    Type: string
  
  - `failure_code` (optional)
    Type: string

- `prepared` (required)
  Type: boolean

- `configured` (required)
  Type: boolean

- `approval_required` (required)
  Type: boolean

- `approval_expires_at` (optional)
  Type: string, date-time; nullable

- `legacy_provider_label` (optional)
  Type: string; nullable

- `legacy_mx_records` (required)
  Type: array
  
  Items:
    Reference: [MxRecord](https://docs.nitrosend.com/api/schemas/mxrecord-ddfac5fe43.md); Type: object

- `setup_note` (optional)
  Type: string; nullable

## MxRecord

Type: object

Schema: [MxRecord](https://docs.nitrosend.com/api/schemas/mxrecord-ddfac5fe43.md)

- `host` (required)
  Type: string

- `preference` (required)
  Type: integer

## EntriDnsRecord

Type: object

Schema: [EntriDnsRecord](https://docs.nitrosend.com/api/schemas/entridnsrecord-a42a1598c4.md)

- `type` (optional)
  Type: string

- `host` (optional)
  Type: string

- `value` (optional)
  Type: string

- `ttl` (optional)
  Type: integer

- `priority` (optional)
  Type: integer; nullable

## Integration

Type: object

Schema: [Integration](https://docs.nitrosend.com/api/schemas/integration-9a42d40a3f.md)

- `id` (optional)
  Type: integer

- `provider` (optional)
  Type: string
  
  enum: ["mailgun","ses","postmark","resend","sendgrid","gmail","microsoft365","smtp","twilio","attio","hubspot","mailchimp","activecampaign","stripe","shopify","apollo"]

- `category` (optional)
  Type: string
  
  enum: ["email","sms","crm","revenue","ecommerce","data"]

- `active` (optional)
  Type: boolean

- `primary` (optional)
  Type: boolean

- `status` (optional)
  Type: string
  
  enum: ["pending","connected","error"]

- `connected_at` (optional)
  Type: string, date-time; nullable

- `last_tested_at` (optional)
  Type: string, date-time; nullable

- `error_message` (optional)
  Type: string; nullable

- `config_summary` (optional)
  Type: object
  
  - `mailbox_address` (optional)
    Type: string, email
    
    Exact address authorized by a connected mailbox.
  
  - `account_type` (optional)
    Type: string
    
    Google mailbox type when available.
    
    enum: ["workspace","personal"]
  
  - `verification_pending` (optional)
    Type: boolean
    
    SMTP address verification code is outstanding.
  
  - `smtp_host` (optional)
    Type: string
  
  - `smtp_port` (optional)
    Type: integer
  
  - `imap_host` (optional)
    Type: string
  
  - `imap_port` (optional)
    Type: integer
  
  - `imap_username` (optional)
    Type: string
  
  - `sent_folder` (optional)
    Type: string
  
  - `junk_folder` (optional)
    Type: string
  
  - `sending_domain_id` (optional)
    Type: integer; nullable
  
  - `sending_identity_id` (optional)
    Type: integer
  
  - `sender_ready` (optional)
    Type: boolean
  
  - `selected_sender` (optional)
    Type: boolean
  
  - `connect_url` (optional)
    Type: string, uri
    
    Dashboard connection and reconnect action.
  
  - `last_synced_at` (optional)
    Type: string, date-time; nullable
    
    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_host` (optional)
    Type: string
    
    ActiveCampaign: the account's API host, from the API URL it was connected with.
  
  - `contacts_reconciled_at` (optional)
    Type: string, date-time
    
    ActiveCampaign: when the last full contact sync started. Runs in between read only contacts ActiveCampaign changed.
  
  - `list_mapping_count` (optional)
    Type: integer
    
    Contact-sync integrations: provider lists (and, for ActiveCampaign, tags) kept as Nitrosend lists.
  
  - `event_capabilities` (optional)
    Type: object
    
    Supported evidence only. Request acceptance is not delivery proof.
    
    - `acceptance` (optional)
      Type: boolean
    
    - `replies` (optional)
      Type: boolean
    
    - `delivery` (optional)
      Type: boolean
    
    - `complaints` (optional)
      Type: boolean
  
  Additional properties: true

- `secret_hints` (optional)
  Type: object
  
  Additional properties: 
    Type: string; nullable

- `created_at` (optional)
  Type: string, date-time

- `updated_at` (optional)
  Type: string, date-time

## SmtpFeedbackPayload

Type: SmtpFeedbackPayload

Schema: [SmtpFeedbackPayload](https://docs.nitrosend.com/api/schemas/smtpfeedbackpayload-db5f52d237.md)

oneOf:
  Type: object
  
  - `type` (required)
    Type: string
    
    enum: ["test"]
  
  Additional properties: false

  Type: object
  
  - `type` (required)
    Type: string
    
    enum: ["delivered","bounced","complained"]
  
  - `message_id` (required)
    Type: string
    
    Original RFC Message-ID, with or without surrounding angle brackets.
    
    maxLength: 255
  
  - `recipient` (required)
    Type: string, email
    
    maxLength: 254
  
  - `occurred_at` (required)
    Type: string, date-time
    
    Outcome time, no more than five minutes in the future.
  
  - `status` (optional)
    Type: string
    
    Required only for bounced events. Recipient failures suppress; policy failures remain delivery_failed observations.
    
    pattern: "^[45]\\.\\d{1,3}\\.\\d{1,3}$"
  
  - `nitrosend_message_id` (optional)
    Type: integer, int64
    
    Optional original X-Nitro-Message-Id, supplied together with dispatch_token to correlate an outcome before the send result is persisted.
    
    minimum: 1
    
    maximum: 9223372036854776000
  
  - `dispatch_token` (optional)
    Type: string
    
    Original X-Nitro-Dispatch header, supplied together with nitrosend_message_id.
    
    maxLength: 2048
  
  allOf:
    Type: unknown
  
  Additional properties: false

## SmtpFeedbackSetup

Type: object

Schema: [SmtpFeedbackSetup](https://docs.nitrosend.com/api/schemas/smtpfeedbacksetup-d5fbfaab57.md)

- `url` (required)
  Type: string, uri

- `signing_secret` (required)
  Type: string
  
  Connection-specific whsec_ key; never included in integration lists or broadcasts.

- `signing_format` (required)
  Type: string
  
  enum: ["standard_webhooks"]

- `events` (required)
  Type: array
  
  maxItems: 20
  
  Items:
    Type: object
    
    - `id` (optional)
      Type: string
    
    - `type` (optional)
      Type: string
      
      enum: ["test","delivered","bounced","complained"]
    
    - `status` (optional)
      Type: string
      
      enum: ["pending","processing","processed","ignored","failed"]
    
    - `received_at` (optional)
      Type: string, date-time
    
    - `processed_at` (optional)
      Type: string, date-time; nullable
    
    - `message_id` (optional)
      Type: string; nullable
    
    - `recipient` (optional)
      Type: string; nullable
    
    - `error_message` (optional)
      Type: string; nullable

## ShopifyMerchantCredentialRequest

Type: object

Schema: [ShopifyMerchantCredentialRequest](https://docs.nitrosend.com/api/schemas/shopifymerchantcredentialrequest-68919b351e.md)

- `shopify` (required)
  Type: object
  
  - `shop` (required)
    Type: string
    
    Permanent myshopify.com domain or shop slug.
  
  - `client_id` (required)
    Type: string
    
    Client ID for the merchant-owned Shopify app.
    
    writeOnly: true
  
  - `client_secret` (required)
    Type: string, password
    
    Client secret for the merchant-owned Shopify app.
    
    writeOnly: true
  
  Additional properties: false

## IntegrationWriteRequest

Type: object

Schema: [IntegrationWriteRequest](https://docs.nitrosend.com/api/schemas/integrationwriterequest-f190c0b2af.md)

- `integration` (required)
  Type: unknown
  
  oneOf:
    Reference: [MailgunIntegrationInput](https://docs.nitrosend.com/api/schemas/mailgunintegrationinput-85c7ec3a86.md); Type: object
  
    Reference: [SesIntegrationInput](https://docs.nitrosend.com/api/schemas/sesintegrationinput-985c0c6d4d.md); Type: object
  
    Reference: [PostmarkIntegrationInput](https://docs.nitrosend.com/api/schemas/postmarkintegrationinput-59f564e679.md); Type: object
  
    Reference: [ResendIntegrationInput](https://docs.nitrosend.com/api/schemas/resendintegrationinput-f4b80f4134.md); Type: object
  
    Reference: [SendgridIntegrationInput](https://docs.nitrosend.com/api/schemas/sendgridintegrationinput-f49ce9ac55.md); Type: object
  
    Reference: [ActiveCampaignIntegrationInput](https://docs.nitrosend.com/api/schemas/activecampaignintegrationinput-0412cfa28f.md); Type: object

## IntegrationSyncConfiguration

Type: object

Schema: [IntegrationSyncConfiguration](https://docs.nitrosend.com/api/schemas/integrationsyncconfiguration-46ed32cba5.md)

- `integration_id` (required)
  Type: integer

- `provider` (required)
  Type: string

- `sync_contract` (required)
  Reference: [IntegrationSyncContract](https://docs.nitrosend.com/api/schemas/integrationsynccontract-13e9430fbb.md); Type: object

## IntegrationSyncContract

Type: object

Schema: [IntegrationSyncContract](https://docs.nitrosend.com/api/schemas/integrationsynccontract-13e9430fbb.md)

- `version` (required)
  Type: integer
  
  enum: [1]

- `mirror_lists` (required)
  Type: boolean

- `updated_at` (optional)
  Type: string, date-time; nullable

- `objects` (required)
  Type: array
  
  maxItems: 25
  
  Items:
    Reference: [IntegrationSyncObjectSelection](https://docs.nitrosend.com/api/schemas/integrationsyncobjectselection-3d0c8cc25f.md); Type: object

## IntegrationSyncObjectSelection

Type: object

Schema: [IntegrationSyncObjectSelection](https://docs.nitrosend.com/api/schemas/integrationsyncobjectselection-3d0c8cc25f.md)

- `object_id` (optional)
  Type: string

- `object_slug` (required)
  Type: string
  
  maxLength: 180

- `label` (optional)
  Type: string
  
  maxLength: 120

- `mode` (required)
  Type: string
  
  enum: ["addressable","related"]

- `enabled` (optional)
  Type: boolean
  
  default: true

- `field_policy` (optional)
  Type: string
  
  enum: ["all_supported","selected"]

- `selected_fields` (optional)
  Type: array
  
  maxItems: 200
  
  Items:
    Type: string
    
    maxLength: 180

- `excluded_fields` (optional)
  Type: array
  
  maxItems: 200
  
  Items:
    Type: string
    
    maxLength: 180

- `relationship` (optional)
  Type: object
  
  - `attribute_slug` (optional)
    Type: string
  
  - `target_object_slug` (optional)
    Type: string
    
    enum: ["people","users"]

- `trait_mapping` (optional)
  Reference: [IntegrationSyncTraitMapping](https://docs.nitrosend.com/api/schemas/integrationsynctraitmapping-4a59c0eaa2.md); Type: object

- `managed_audience_mapping_key` (optional)
  Type: string

- `mirror_lists` (optional)
  Type: boolean

## IntegrationSyncTraitMapping

Type: object

Schema: [IntegrationSyncTraitMapping](https://docs.nitrosend.com/api/schemas/integrationsynctraitmapping-4a59c0eaa2.md)

- `kind` (required)
  Type: string
  
  enum: ["deal_pipeline"]

- `stage_attribute` (required)
  Type: string
  
  maxLength: 180

- `closed_stage_values` (required)
  Type: array
  
  minItems: 1
  
  maxItems: 50
  
  Items:
    Type: string
    
    maxLength: 120

- `amount_attribute` (optional)
  Type: string
  
  maxLength: 180

- `currency_attribute` (optional)
  Type: string
  
  maxLength: 180

## IntegrationSyncConfigurationWriteRequest

Type: object

Schema: [IntegrationSyncConfigurationWriteRequest](https://docs.nitrosend.com/api/schemas/integrationsyncconfigurationwriterequest-34d5a37068.md)

- `sync_contract` (required)
  Reference: [IntegrationSyncContract](https://docs.nitrosend.com/api/schemas/integrationsynccontract-13e9430fbb.md); Type: object

## IntegrationSyncDiscovery

Type: object

Schema: [IntegrationSyncDiscovery](https://docs.nitrosend.com/api/schemas/integrationsyncdiscovery-04ac2fff94.md)

- `provider` (required)
  Type: string

- `version` (required)
  Type: integer
  
  enum: [1]

- `truncated` (required)
  Type: boolean

- `objects` (required)
  Type: array
  
  maxItems: 100
  
  Items:
    Type: object
    
    - `object_id` (required)
      Type: string
    
    - `object_slug` (required)
      Type: string
    
    - `singular_noun` (optional)
      Type: string
    
    - `plural_noun` (optional)
      Type: string
    
    - `eligible` (required)
      Type: boolean
    
    - `recommended_mode` (optional)
      Type: string; nullable
      
      enum: ["addressable","related"]
    
    - `ineligible_reason` (optional)
      Type: string; nullable
    
    - `attributes_truncated` (optional)
      Type: boolean
    
    - `attributes` (required)
      Type: array
      
      maxItems: 500
      
      Items:
        Reference: [IntegrationSyncDiscoveredAttribute](https://docs.nitrosend.com/api/schemas/integrationsyncdiscoveredattribute-f52e996198.md); Type: object
    
    - `relationship_attributes` (optional)
      Type: array
      
      maxItems: 500
      
      Items:
        Reference: [IntegrationSyncDiscoveredAttribute](https://docs.nitrosend.com/api/schemas/integrationsyncdiscoveredattribute-f52e996198.md); Type: object

## IntegrationSyncDiscoveredAttribute

Type: object

Schema: [IntegrationSyncDiscoveredAttribute](https://docs.nitrosend.com/api/schemas/integrationsyncdiscoveredattribute-f52e996198.md)

- `attribute_id` (required)
  Type: string

- `attribute_slug` (required)
  Type: string

- `title` (optional)
  Type: string

- `type` (required)
  Type: string

- `classification` (required)
  Type: string
  
  enum: ["canonical_scalar","fact_only","relationship"]

- `required` (optional)
  Type: boolean

- `unique` (optional)
  Type: boolean

- `multiselect` (optional)
  Type: boolean

- `target_object_slugs` (optional)
  Type: array
  
  Items:
    Type: string

- `options` (optional)
  Type: array
  
  maxItems: 100
  
  Items:
    Type: string
    
    maxLength: 120

## MailgunIntegrationInput

Type: object

Schema: [MailgunIntegrationInput](https://docs.nitrosend.com/api/schemas/mailgunintegrationinput-85c7ec3a86.md)

- `provider` (required)
  Type: string
  
  enum: ["mailgun"]

- `api_key` (required)
  Type: string

- `domain` (required)
  Type: string
  
  Mailgun sending domain

- `region` (optional)
  Type: string; nullable
  
  Optional Mailgun region hint

- `active` (optional)
  Type: boolean
  
  default: true

## SesIntegrationInput

Type: object

Schema: [SesIntegrationInput](https://docs.nitrosend.com/api/schemas/sesintegrationinput-985c0c6d4d.md)

- `provider` (required)
  Type: string
  
  enum: ["ses"]

- `access_key_id` (required)
  Type: string

- `secret_access_key` (required)
  Type: string

- `region` (required)
  Type: string
  
  AWS SES region

- `active` (optional)
  Type: boolean
  
  default: true

## PostmarkIntegrationInput

Type: object

Schema: [PostmarkIntegrationInput](https://docs.nitrosend.com/api/schemas/postmarkintegrationinput-59f564e679.md)

- `provider` (required)
  Type: string
  
  enum: ["postmark"]

- `server_token` (required)
  Type: string
  
  Postmark server token for sending email

- `account_token` (required)
  Type: string
  
  Postmark account token for domains API access

- `active` (optional)
  Type: boolean
  
  default: true

## ResendIntegrationInput

Type: object

Schema: [ResendIntegrationInput](https://docs.nitrosend.com/api/schemas/resendintegrationinput-f4b80f4134.md)

- `provider` (required)
  Type: string
  
  enum: ["resend"]

- `api_key` (required)
  Type: string

- `active` (optional)
  Type: boolean
  
  default: true

## SendgridIntegrationInput

Type: object

Schema: [SendgridIntegrationInput](https://docs.nitrosend.com/api/schemas/sendgridintegrationinput-f49ce9ac55.md)

- `provider` (required)
  Type: string
  
  enum: ["sendgrid"]

- `api_key` (required)
  Type: string

- `active` (optional)
  Type: boolean
  
  default: true

## ActiveCampaignIntegrationInput

Type: object

Schema: [ActiveCampaignIntegrationInput](https://docs.nitrosend.com/api/schemas/activecampaignintegrationinput-0412cfa28f.md)

- `provider` (required)
  Type: string
  
  enum: ["activecampaign"]

- `api_url` (required)
  Type: string, uri
  
  The API URL from ActiveCampaign Settings > Developer, like https://youraccount.api-us1.com. Only https on an ActiveCampaign API host is accepted.

- `api_key` (required)
  Type: string
  
  writeOnly: true

- `active` (optional)
  Type: boolean
  
  default: true

## Plan

Type: object

Schema: [Plan](https://docs.nitrosend.com/api/schemas/plan-fa8ed0bdab.md)

- `id` (optional)
  Type: integer

- `name` (optional)
  Type: string

- `active` (optional)
  Type: boolean

- `change_timing` (optional)
  Type: string; nullable
  
  Available on account-scoped base offers; uses the same rule as subscription change scheduling.
  
  enum: ["immediate","renewal"]

- `change_at` (optional)
  Type: string, date-time; nullable

- `change_blockers` (optional)
  Type: array
  
  Account-scoped base-plan capacity reasons preventing a voluntary change. Cancellation and return to Free remain available; no resources are deleted.
  
  Items:
    Type: object
    
    - `resource` (required)
      Type: string
      
      enum: ["brands","domains","seats","inboxes"]
    
    - `used` (required)
      Type: integer
      
      minimum: 0
    
    - `limit` (required)
      Type: integer
      
      minimum: 0
    
    - `message` (required)
      Type: string

- `probation_recipient_cap_24h` (optional)
  Type: integer
  
  Same allowance as Standard. A one-time initial bulk observation can briefly defer bulk dispatch, not individual transactional mail.
  
  minimum: 0

- `standard_recipient_cap_24h` (optional)
  Type: integer
  
  minimum: 0

- `trusted_recipient_cap_24h` (optional)
  Type: integer
  
  Full allowance on earning Trusted; zero represents a contracted unlimited allowance. Credits and safety remain separate.
  
  minimum: 0

- `entitlements` (optional)
  Reference: [BillingEntitlements](https://docs.nitrosend.com/api/schemas/billingentitlements-6434d07335.md); Type: object

## EmailDesign

Type: object

Email template design document

Schema: [EmailDesign](https://docs.nitrosend.com/api/schemas/emaildesign-bfd9d648d2.md)

- `version` (optional)
  Reference: version; Type: integer
  
  minimum: 1

- `sections` (optional)
  Reference: sections; Type: array

- `theme` (optional)
  Reference: theme; Type: object
  
  Theme overrides merged on top of brand theme

Additional properties: false

## EmailAccessibilityLint

Type: object

Advisory accessibility lint result for rendered email previews

Schema: [EmailAccessibilityLint](https://docs.nitrosend.com/api/schemas/emailaccessibilitylint-22fefb001e.md)

- `product_bindings` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `path` (optional)
      Type: string
    
    - `available` (optional)
      Type: integer
    
    - `displayed` (optional)
      Type: integer
    
    - `truncated` (optional)
      Type: boolean

- `valid` (optional)
  Type: boolean
  
  Always true while accessibility lint is advisory-only

- `warnings` (optional)
  Type: array
  
  Items:
    Reference: [EmailAccessibilityWarning](https://docs.nitrosend.com/api/schemas/emailaccessibilitywarning-9211016abb.md); Type: object

## EmailAccessibilityWarning

Type: object

Schema: [EmailAccessibilityWarning](https://docs.nitrosend.com/api/schemas/emailaccessibilitywarning-9211016abb.md)

- `level` (optional)
  Type: string
  
  Example:
  
  ```json
  "warning"
  ```

- `rule` (optional)
  Type: string
  
  Example:
  
  ```json
  "image_alt_text"
  ```

- `message` (optional)
  Type: string

- `suggested_fix` (optional)
  Type: string

- `count` (optional)
  Type: integer

- `min_ratio` (optional)
  Type: number, float

## EmailSection

Type: object

Schema: [EmailSection](https://docs.nitrosend.com/api/schemas/emailsection-05c9f19b09.md)

- `binding` (optional)
  Type: object
  
  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.
  
  - `path` (required)
    Type: string
    
    pattern: "^(?:event(?:\\.[a-zA-Z_][a-zA-Z0-9_]*)+|catalog\\.(?:best_sellers|new_arrivals))$"
  
  - `index` (optional)
    Type: integer
    
    minimum: 0
    
    maximum: 49
  
  - `limit` (optional)
    Type: integer
    
    minimum: 1
    
    maximum: 50
  
  Additional properties: false

- `block` (optional)
  Type: object
  
  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.
  
  - `template_id` (required)
    Type: integer
    
    minimum: 1
  
  - `key` (optional)
    Type: string
    
    pattern: "^[0-9a-f]{8}$"
  
  Additional properties: false

- `type` (required)
  Type: string
  
  enum: ["header","hero","text","image","button","columns","product","products","gallery","social","divider","spacer","footer"]

- `props` (optional)
  Type: object
  
  Section-specific properties (see email component spec)
  
  Additional properties: true

- `styles` (optional)
  Type: object
  
  - `background_color` (optional)
    Type: string
  
  - `section_background_color` (optional)
    Type: string
  
  - `padding` (optional)
    Type: string
  
  - `align` (optional)
    Type: string
    
    enum: ["left","center","right"]
  
  - `scale` (optional)
    Type: string
    
    enum: ["display","poster"]
  
  - `font_size` (optional)
    Type: integer
  
  - `text_color` (optional)
    Type: string
  
  - `shape` (optional)
    Type: string
    
    enum: ["square","rounded","arch","circle"]
  
  - `remove_gap` (optional)
    Type: boolean
  
  - `border_radius` (optional)
    Type: integer
  
  Additional properties: false

## EmailComponentSpec

Type: object

Full schema for email design sections. Each component has type,
description, props (with types, required flags, defaults), and tips.


Schema: [EmailComponentSpec](https://docs.nitrosend.com/api/schemas/emailcomponentspec-39b992201d.md)

- `version` (required)
  Type: integer

- `design_guidelines` (required)
  Type: string

- `renderer_version` (required)
  Type: string
  
  The @nitrosend/email-renderer version sent email is rendered with. The editor checks its own renderer against it.

- `components` (required)
  Type: array
  
  Items:
    Type: object
    
    - `type` (required)
      Type: string
    
    - `description` (required)
      Type: string
    
    - `tips` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `props` (required)
      Type: object
      
      Additional properties: 
        Type: object
        
        - `type` (required)
          Type: string
        
        - `required` (optional)
          Type: boolean
        
        - `default` (optional)
          Type: unknown
        
        - `description` (optional)
          Type: string
        
        - `enum` (optional)
          Type: array
          
          Items:
            Type: string
        
        - `items` (optional)
          Type: object
          
          Additional properties: 
            Type: object
            
            - `type` (required)
              Type: string
            
            - `description` (required)
              Type: string
            
            Additional properties: false
        
        - `server_owned` (optional)
          Type: boolean
        
        - `unset_when_empty` (optional)
          Type: boolean
          
          An empty value is allowed in a draft; delivery leaves the section out.
        
        - `theme_key` (optional)
          Type: string
        
        Additional properties: false
    
    Additional properties: false

- `style_attributes` (required)
  Type: array
  
  Standard per-section style attribute registry.
  
  Items:
    Type: object
    
    - `key` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["color","spacing","enum","number","boolean"]
    
    - `applies_to` (required)
      Type: unknown
    
    - `default` (optional)
      Type: unknown
    
    - `theme_fallback` (optional)
      Type: string
    
    - `description` (required)
      Type: string
    
    - `min` (optional)
      Type: integer
    
    - `max` (optional)
      Type: integer
    
    - `values` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `target` (required)
      Type: object
      
      - `el` (required)
        Type: string
        
        enum: ["section","content","shape"]
      
      - `attr` (optional)
        Type: string
      
      Additional properties: false
    
    Additional properties: false

- `preview_document` (required)
  Type: object
  
  - `parameter` (required)
    Type: string
  
  - `description` (required)
    Type: string
  
  - `example` (required)
    Type: object
    
    Additional properties: true
  
  Additional properties: false

- `variables` (required)
  Type: object
  
  Merge variables grouped by source namespace.
  
  Additional properties: 
    Type: array
    
    Items:
      Type: object
      
      - `name` (required)
        Type: string
      
      - `description` (required)
        Type: string
      
      Additional properties: false

- `filters` (required)
  Type: array
  
  Items:
    Type: object
    
    - `name` (required)
      Type: string
    
    - `syntax` (required)
      Type: string
    
    - `description` (required)
      Type: string
    
    Additional properties: false

- `theme_attributes` (required)
  Type: array
  
  Brand Kit theme attribute registry (single source of truth for the editor).
  
  Items:
    Type: object
    
    - `key` (required)
      Type: string
    
    - `label` (required)
      Type: string
    
    - `type` (required)
      Type: string
      
      enum: ["color","font","number","enum","spacing","string","image","array"]
    
    - `default` (optional)
      Type: unknown
    
    - `category` (required)
      Type: string
      
      enum: ["color","font","visual_identity","identity"]
    
    - `slot` (optional)
      Type: string
    
    - `surfaces` (required)
      Type: array
      
      Items:
        Type: string
    
    - `min` (optional)
      Type: integer
    
    - `max` (optional)
      Type: integer
    
    - `values` (optional)
      Type: array
      
      Items:
        Type: string
    
    - `options` (optional)
      Type: array
      
      Items:
        Type: object
        
        - `value` (optional)
          Type: string
        
        - `label` (optional)
          Type: string
        
        - `description` (optional)
          Type: string
    
    - `transform_table` (optional)
      Type: object
      
      Additional properties: 
        Type: string
    
    - `column` (optional)
      Type: boolean
    
    - `storage` (optional)
      Type: string
    
    - `placeholder` (optional)
      Type: string
    
    - `value_resolver` (optional)
      Type: string
    
    - `server_owned` (optional)
      Type: boolean
    
    - `description` (optional)
      Type: string
    
    Additional properties: false

Additional properties: false

## FlowSpec

Type: 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.


Schema: [FlowSpec](https://docs.nitrosend.com/api/schemas/flowspec-bdd31bc61e.md)

- `filters` (optional)
  Reference: filters; Type: object

- `triggers` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `title` (optional)
      Type: string
    
    - `event` (optional)
      Type: string
    
    - `description` (optional)
      Type: string
      
      What fires the trigger.
    
    - `variables` (optional)
      Type: object
      
      - `paths` (optional)
        Type: array
        
        Items:
          Type: object
          
          - `path` (optional)
            Type: string
            
            Declared event payload path.
          
          - `type` (optional)
            Type: string
            
            enum: ["string","integer","number","boolean","object","array"]
      
      - `filters` (optional)
        Reference: filters; Type: object

- `filter_limits` (optional)
  Type: object
  
  Limits every filter tree is held to on save. A tree past either limit is refused with invalid_filter.
  
  - `max_depth` (optional)
    Type: integer
    
    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_group` (optional)
    Type: integer
    
    The most conditions one group may hold.

- `steps` (optional)
  Type: array
  
  Items:
    Type: object
    
    - `type` (optional)
      Type: string
    
    - `title` (optional)
      Type: string
    
    - `summary` (optional)
      Type: string
    
    - `params` (optional)
      Type: object
      
      Additional properties: 
        Type: object
        
        - `label` (optional)
          Type: string
        
        - `type` (optional)
          Type: string
        
        - `required` (optional)
          Type: boolean
        
        - `default` (optional)
          Type: unknown
        
        - `description` (optional)
          Type: string
