Home

Nitrosend API

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

Multi-channel marketing automation API. Send email campaigns, build automation flows, manage contacts and segments, track events, and configure your brand — all via a single REST API.

Authentication

All /v1/my/* endpoints require authentication via Bearer token. Two token types are accepted (tried in order):

  1. API Key — Authorization: Bearer nskey_live_...
  2. JWT — Authorization: Bearer <jwt> (obtained from POST /v1/login)

Pagination

Paginated endpoints return these headers:

  • X-Total-Count — total records
  • X-Total-Pages — total pages
  • X-Page-Number — current page
  • X-Next-Page — next page (omitted on last page)
  • X-Prev-Page — previous page (omitted on first page)

Use page and limit (or per) query params to control pagination. Maximum limit is 100, default is 30.

Error Responses

All errors return a consistent JSON shape:

{
  "code": 422,
  "message": "Description of error",
  "error": true,
  "validation_errors": { "field": ["error message"] }
}

The validation_errors key is only present on 422 responses.

Authentication

BearerAuthhttp

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Scheme: bearer

Auth

Login, logout, and registration

Create a new account

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

Body

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

Response

201Createdobject

Account created

422Unprocessable Entityobject & object

Validation failed

Create a new account
curl -X POST 'https://api.nitrosend.com/v1/signup' \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "mobile": "string",
      "invite_token": "string",
      "password": "********",
      "password_confirmation": "********"
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/signup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "user": {
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "mobile": "string",
        "invite_token": "string",
        "password": "********",
        "password_confirmation": "********"
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "user": {
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "mobile": "string",
    "invite_token": "string",
    "password": "********",
    "password_confirmation": "********"
  }
}

response = requests.post('https://api.nitrosend.com/v1/signup', json=payload)
data = response.json()
Request Body
{
  "user": {
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "mobile": "string",
    "invite_token": "string",
    "password": "********",
    "password_confirmation": "********"
  }
}
{
  "id": 0,
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "country_code": "string",
  "admin": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Sign in and receive a JWT

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

Body

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

Response

200OKobject

Signed in

401Unauthorizedobject

Not authenticated

Sign in and receive a JWT
curl -X POST 'https://api.nitrosend.com/v1/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "email": "user@example.com",
      "password": "********"
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "user": {
        "email": "user@example.com",
        "password": "********"
      }
    }),
});

const data = await response.json();
import requests

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

response = requests.post('https://api.nitrosend.com/v1/login', json=payload)
data = response.json()
Request Body
{
  "user": {
    "email": "user@example.com",
    "password": "********"
  }
}
{
  "id": 0,
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "country_code": "string",
  "admin": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Sign out and revoke JWT

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

Response

204No Content

Signed out

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Sign out and revoke JWT
curl -X DELETE 'https://api.nitrosend.com/v1/logout'
const response = await fetch('https://api.nitrosend.com/v1/logout', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/logout')
data = response.json()

Get OAuth popup context

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

Returns the account-selection and subscription context used by the /oauth/connect popup. This endpoint accepts the normal Bearer JWT and, for popup resume flows, the authenticated browser session cookie established by Devise/OmniAuth.

Response

200OKobject

Popup context

401Unauthorizedobject

Not authenticated

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get OAuth popup context
curl -X GET 'https://api.nitrosend.com/v1/oauth/me'
const response = await fetch('https://api.nitrosend.com/v1/oauth/me', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/oauth/me')
data = response.json()
{
  "accounts": [
    {
      "id": 0,
      "name": "string",
      "can_manage": true,
      "needs_subscribe": true
    }
  ],
  "plans": [
    {
      "id": 0,
      "name": "string",
      "slug": "string",
      "base_price_cents": 0,
      "interval": "string"
    }
  ],
  "stripe_publishable_key": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Subscribe the selected OAuth popup account

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

Finalizes plan selection for the /oauth/connect popup before the browser returns to the Doorkeeper consent screen. This endpoint accepts the normal Bearer JWT and, for popup resume flows, the authenticated browser session cookie established by Devise/OmniAuth.

Body

application/json
plan_idintegerrequired
account_idinteger | null
stripe_tokenstring | null

Response

200OKobject

Popup can continue to consent

401Unauthorizedobject

Not authenticated

422Unprocessable Entityobject

Account or plan selection failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Subscribe the selected OAuth popup account
curl -X POST 'https://api.nitrosend.com/v1/oauth/subscribe' \
  -H 'Content-Type: application/json' \
  -d '{
    "plan_id": 0,
    "account_id": 0,
    "stripe_token": "string"
  }'
const response = await fetch('https://api.nitrosend.com/v1/oauth/subscribe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "plan_id": 0,
      "account_id": 0,
      "stripe_token": "string"
    }),
});

const data = await response.json();
import requests

payload = {
  "plan_id": 0,
  "account_id": 0,
  "stripe_token": "string"
}

response = requests.post('https://api.nitrosend.com/v1/oauth/subscribe', json=payload)
data = response.json()
Request Body
{
  "plan_id": 0,
  "account_id": 0,
  "stripe_token": "string"
}
{
  "next_step": "consent"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "error": "string"
}

Create a CSRF-safe OAuth provider launch URL

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

Mints a short-lived launch URL for Google or GitHub sign-in. The frontend follows the returned API-origin launch page, which renders the real POST form to /auth/:provider with a valid Rails authenticity token. This preserves OmniAuth's POST-only request phase and CSRF protection for both the app popup flow and the /oauth/connect agent popup flow.

Body

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

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

Response

200OKobject

Launch URL created

400Bad Requestobject

Invalid provider or resume URL

Create a CSRF-safe OAuth provider launch URL
curl -X POST 'https://api.nitrosend.com/v1/oauth/launch' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "google_oauth2",
    "auth_intent": "app",
    "auth_step": "login",
    "resume_url": "https://example.com"
  }'
const response = await fetch('https://api.nitrosend.com/v1/oauth/launch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "provider": "google_oauth2",
      "auth_intent": "app",
      "auth_step": "login",
      "resume_url": "https://example.com"
    }),
});

const data = await response.json();
import requests

payload = {
  "provider": "google_oauth2",
  "auth_intent": "app",
  "auth_step": "login",
  "resume_url": "https://example.com"
}

response = requests.post('https://api.nitrosend.com/v1/oauth/launch', json=payload)
data = response.json()
Request Body
{
  "provider": "google_oauth2",
  "auth_intent": "app",
  "auth_step": "login",
  "resume_url": "https://example.com"
}
{
  "launch_url": "https://example.com"
}
{
  "error": "string"
}

User

Current user profile

Get current user profile

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

Response

200OKobject

User profile

401Unauthorizedobject

Not authenticated

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get current user profile
curl -X GET 'https://api.nitrosend.com/v1/my/user'
const response = await fetch('https://api.nitrosend.com/v1/my/user', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/user')
data = response.json()
{
  "id": 0,
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "country_code": "string",
  "admin": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Update current user profile

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

Body

application/json
first_namestring
last_namestring
emailstring<email>
mobilestring

Response

200OKobject

Updated user

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update current user profile
curl -X PATCH 'https://api.nitrosend.com/v1/my/user' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "mobile": "string"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/user', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "mobile": "string"
    }),
});

const data = await response.json();
import requests

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

response = requests.patch('https://api.nitrosend.com/v1/my/user', json=payload)
data = response.json()
Request Body
{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string"
}
{
  "id": 0,
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "country_code": "string",
  "admin": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Account

Account settings and configuration

Get account details

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

Response

200OKobject

Account with brands and billing

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get account details
curl -X GET 'https://api.nitrosend.com/v1/my/account'
const response = await fetch('https://api.nitrosend.com/v1/my/account', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/account')
data = response.json()
200
{
  "id": 0,
  "name": "string",
  "avatar": "string",
  "banner": "string",
  "account_tier": "free",
  "safe_mode_enabled": true,
  "billing": {
    "plan_name": "string",
    "wallet_balance_cents": 0,
    "auto_topup": true,
    "resources": {
      "email": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      },
      "sms": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      },
      "ai": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      }
    },
    "lifetime": {
      "email_sent": 0,
      "sms_sent": 0,
      "ai_used": 0
    }
  },
  "brands": [
    {
      "id": 0,
      "sid": "string",
      "account_id": 0,
      "brand_color": "string",
      "text_color": "string",
      "bg_color": "string",
      "font_heading": "string",
      "font_body": "string",
      "style_notes": "string",
      "tone": "string",
      "company_description": "string",
      "industry": "string",
      "example_copy": [
        "string"
      ],
      "default_header": {},
      "default_footer": {},
      "default_theme": {},
      "physical_address": "string",
      "company_name": "string",
      "source_url": "string",
      "last_scraped_at": "2024-01-15T09:30:00Z",
      "links": [
        {
          "url": "string",
          "icon": "string",
          "title": "string"
        }
      ],
      "logo": "string",
      "complete": true,
      "email_from_name": "string",
      "email_from_email": "string",
      "email_reply_to": "string",
      "test_email_recipients": [
        "user@example.com"
      ],
      "onboarding_state": {},
      "onboarding": {
        "steps": {},
        "progress": {
          "completed": 0,
          "total": 0
        }
      },
      "domain_verified": true,
      "can_send": true,
      "subscribed_contacts_count": 0,
      "using_sandbox": true,
      "sandbox_email": "string",
      "sandbox_monthly_cap": 0,
      "sandbox_sends_remaining": 0,
      "capabilities": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "team": {
    "seat_limit": 0,
    "seat_count": 0,
    "member_count": 0,
    "invite_count": 0,
    "current_role": "string",
    "can_manage_team": true
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Update account settings

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

Body

application/json
namestring
avatarstring

Signed blob ID

bannerstring

Signed blob ID

Response

200OKobject

Updated account

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update account settings
curl -X PATCH 'https://api.nitrosend.com/v1/my/account' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "avatar": "string",
    "banner": "string"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/account', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "avatar": "string",
      "banner": "string"
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "avatar": "string",
  "banner": "string"
}

response = requests.patch('https://api.nitrosend.com/v1/my/account', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "avatar": "string",
  "banner": "string"
}
{
  "id": 0,
  "name": "string",
  "avatar": "string",
  "banner": "string",
  "account_tier": "free",
  "safe_mode_enabled": true,
  "billing": {
    "plan_name": "string",
    "wallet_balance_cents": 0,
    "auto_topup": true,
    "resources": {
      "email": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      },
      "sms": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      },
      "ai": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      }
    },
    "lifetime": {
      "email_sent": 0,
      "sms_sent": 0,
      "ai_used": 0
    }
  },
  "brands": [
    {
      "id": 0,
      "sid": "string",
      "account_id": 0,
      "brand_color": "string",
      "text_color": "string",
      "bg_color": "string",
      "font_heading": "string",
      "font_body": "string",
      "style_notes": "string",
      "tone": "string",
      "company_description": "string",
      "industry": "string",
      "example_copy": [
        "string"
      ],
      "default_header": {},
      "default_footer": {},
      "default_theme": {},
      "physical_address": "string",
      "company_name": "string",
      "source_url": "string",
      "last_scraped_at": "2024-01-15T09:30:00Z",
      "links": [
        {
          "url": "string",
          "icon": "string",
          "title": "string"
        }
      ],
      "logo": "string",
      "complete": true,
      "email_from_name": "string",
      "email_from_email": "string",
      "email_reply_to": "string",
      "test_email_recipients": [
        "user@example.com"
      ],
      "onboarding_state": {},
      "onboarding": {
        "steps": {},
        "progress": {
          "completed": 0,
          "total": 0
        }
      },
      "domain_verified": true,
      "can_send": true,
      "subscribed_contacts_count": 0,
      "using_sandbox": true,
      "sandbox_email": "string",
      "sandbox_monthly_cap": 0,
      "sandbox_sends_remaining": 0,
      "capabilities": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "team": {
    "seat_limit": 0,
    "seat_count": 0,
    "member_count": 0,
    "invite_count": 0,
    "current_role": "string",
    "can_manage_team": true
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

List accessible accounts

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

Response

200OKArray<object>

Accessible accounts

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List accessible accounts
curl -X GET 'https://api.nitrosend.com/v1/my/accounts'
const response = await fetch('https://api.nitrosend.com/v1/my/accounts', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/accounts')
data = response.json()
200
[
  {
    "id": 0,
    "name": "string",
    "avatar": "string",
    "banner": "string",
    "account_tier": "free",
    "safe_mode_enabled": true,
    "billing": {
      "plan_name": "string",
      "wallet_balance_cents": 0,
      "auto_topup": true,
      "resources": {
        "email": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        },
        "sms": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        },
        "ai": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        }
      },
      "lifetime": {
        "email_sent": 0,
        "sms_sent": 0,
        "ai_used": 0
      }
    },
    "brands": [
      {
        "id": 0,
        "sid": "string",
        "account_id": 0,
        "brand_color": "string",
        "text_color": "string",
        "bg_color": "string",
        "font_heading": "string",
        "font_body": "string",
        "style_notes": "string",
        "tone": "string",
        "company_description": "string",
        "industry": "string",
        "example_copy": [
          "string"
        ],
        "default_header": {},
        "default_footer": {},
        "default_theme": {},
        "physical_address": "string",
        "company_name": "string",
        "source_url": "string",
        "last_scraped_at": "2024-01-15T09:30:00Z",
        "links": [
          {
            "url": "string",
            "icon": "string",
            "title": "string"
          }
        ],
        "logo": "string",
        "complete": true,
        "email_from_name": "string",
        "email_from_email": "string",
        "email_reply_to": "string",
        "test_email_recipients": [
          "user@example.com"
        ],
        "onboarding_state": {},
        "onboarding": {
          "steps": {},
          "progress": {
            "completed": 0,
            "total": 0
          }
        },
        "domain_verified": true,
        "can_send": true,
        "subscribed_contacts_count": 0,
        "using_sandbox": true,
        "sandbox_email": "string",
        "sandbox_monthly_cap": 0,
        "sandbox_sends_remaining": 0,
        "capabilities": {},
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ],
    "team": {
      "seat_limit": 0,
      "seat_count": 0,
      "member_count": 0,
      "invite_count": 0,
      "current_role": "string",
      "can_manage_team": true
    },
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Get team metadata for the current account

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

Response

200OKobject

Team metadata

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get team metadata for the current account
curl -X GET 'https://api.nitrosend.com/v1/my/account/team'
const response = await fetch('https://api.nitrosend.com/v1/my/account/team', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/account/team')
data = response.json()
200
{
  "account": {
    "id": 0,
    "name": "string",
    "avatar": "string",
    "banner": "string",
    "account_tier": "free",
    "safe_mode_enabled": true,
    "billing": {
      "plan_name": "string",
      "wallet_balance_cents": 0,
      "auto_topup": true,
      "resources": {
        "email": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        },
        "sms": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        },
        "ai": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        }
      },
      "lifetime": {
        "email_sent": 0,
        "sms_sent": 0,
        "ai_used": 0
      }
    },
    "brands": [
      {
        "id": 0,
        "sid": "string",
        "account_id": 0,
        "brand_color": "string",
        "text_color": "string",
        "bg_color": "string",
        "font_heading": "string",
        "font_body": "string",
        "style_notes": "string",
        "tone": "string",
        "company_description": "string",
        "industry": "string",
        "example_copy": [
          "string"
        ],
        "default_header": {},
        "default_footer": {},
        "default_theme": {},
        "physical_address": "string",
        "company_name": "string",
        "source_url": "string",
        "last_scraped_at": "2024-01-15T09:30:00Z",
        "links": [
          {
            "url": "string",
            "icon": "string",
            "title": "string"
          }
        ],
        "logo": "string",
        "complete": true,
        "email_from_name": "string",
        "email_from_email": "string",
        "email_reply_to": "string",
        "test_email_recipients": [
          "user@example.com"
        ],
        "onboarding_state": {},
        "onboarding": {
          "steps": {},
          "progress": {
            "completed": 0,
            "total": 0
          }
        },
        "domain_verified": true,
        "can_send": true,
        "subscribed_contacts_count": 0,
        "using_sandbox": true,
        "sandbox_email": "string",
        "sandbox_monthly_cap": 0,
        "sandbox_sends_remaining": 0,
        "capabilities": {},
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ],
    "team": {
      "seat_limit": 0,
      "seat_count": 0,
      "member_count": 0,
      "invite_count": 0,
      "current_role": "string",
      "can_manage_team": true
    },
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "memberships": [
    {
      "id": 0,
      "role": "member",
      "user_id": 0,
      "email": "user@example.com",
      "name": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "invites": [
    {
      "id": 0,
      "account_id": 0,
      "email": "user@example.com",
      "role": "member",
      "token": "string",
      "status": "pending",
      "accepted_at": "2024-01-15T09:30:00Z",
      "revoked_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "accessible_accounts": [
    {
      "id": 0,
      "name": "string",
      "avatar": "string",
      "banner": "string",
      "account_tier": "free",
      "safe_mode_enabled": true,
      "billing": {
        "plan_name": "string",
        "wallet_balance_cents": 0,
        "auto_topup": true,
        "resources": {
          "email": {
            "used": 0,
            "allowance": 0,
            "remaining": 0,
            "overage_rate": 0
          },
          "sms": {
            "used": 0,
            "allowance": 0,
            "remaining": 0,
            "overage_rate": 0
          },
          "ai": {
            "used": 0,
            "allowance": 0,
            "remaining": 0,
            "overage_rate": 0
          }
        },
        "lifetime": {
          "email_sent": 0,
          "sms_sent": 0,
          "ai_used": 0
        }
      },
      "brands": [
        {
          "id": 0,
          "sid": "string",
          "account_id": 0,
          "brand_color": "string",
          "text_color": "string",
          "bg_color": "string",
          "font_heading": "string",
          "font_body": "string",
          "style_notes": "string",
          "tone": "string",
          "company_description": "string",
          "industry": "string",
          "example_copy": [
            "string"
          ],
          "default_header": {},
          "default_footer": {},
          "default_theme": {},
          "physical_address": "string",
          "company_name": "string",
          "source_url": "string",
          "last_scraped_at": "2024-01-15T09:30:00Z",
          "links": [
            {
              "url": "string",
              "icon": "string",
              "title": "string"
            }
          ],
          "logo": "string",
          "complete": true,
          "email_from_name": "string",
          "email_from_email": "string",
          "email_reply_to": "string",
          "test_email_recipients": [
            "user@example.com"
          ],
          "onboarding_state": {},
          "onboarding": {
            "steps": {},
            "progress": {
              "completed": 0,
              "total": 0
            }
          },
          "domain_verified": true,
          "can_send": true,
          "subscribed_contacts_count": 0,
          "using_sandbox": true,
          "sandbox_email": "string",
          "sandbox_monthly_cap": 0,
          "sandbox_sends_remaining": 0,
          "capabilities": {},
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z"
        }
      ],
      "team": {
        "seat_limit": 0,
        "seat_count": 0,
        "member_count": 0,
        "invite_count": 0,
        "current_role": "string",
        "can_manage_team": true
      },
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

List account memberships

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

Response

200OKArray<object>

Memberships

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List account memberships
curl -X GET 'https://api.nitrosend.com/v1/my/account/memberships'
const response = await fetch('https://api.nitrosend.com/v1/my/account/memberships', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/account/memberships')
data = response.json()
200
[
  {
    "id": 0,
    "role": "member",
    "user_id": 0,
    "email": "user@example.com",
    "name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Remove a membership

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

Parameters

idintegerrequiredpath

Response

200OKobject

Removed membership

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Remove a membership
curl -X DELETE 'https://api.nitrosend.com/v1/my/account/memberships/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/account/memberships/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/account/memberships/{id}')
data = response.json()
200
{
  "id": 0,
  "role": "member",
  "user_id": 0,
  "email": "user@example.com",
  "name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Update a membership role

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

Body

application/json
rolestringmemberadmin

Parameters

idintegerrequiredpath

Response

200OKobject

Updated membership

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a membership role
curl -X PATCH 'https://api.nitrosend.com/v1/my/account/memberships/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "role": "member"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/account/memberships/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "role": "member"
    }),
});

const data = await response.json();
import requests

payload = {
  "role": "member"
}

response = requests.patch('https://api.nitrosend.com/v1/my/account/memberships/{id}', json=payload)
data = response.json()
Request Body
{
  "role": "member"
}
{
  "id": 0,
  "role": "member",
  "user_id": 0,
  "email": "user@example.com",
  "name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

List account invites

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

Response

200OKArray<object>

Invites

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List account invites
curl -X GET 'https://api.nitrosend.com/v1/my/account/invites'
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/account/invites')
data = response.json()
200
[
  {
    "id": 0,
    "account_id": 0,
    "email": "user@example.com",
    "role": "member",
    "token": "string",
    "status": "pending",
    "accepted_at": "2024-01-15T09:30:00Z",
    "revoked_at": "2024-01-15T09:30:00Z",
    "expires_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Create an account invite

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

Body

application/json
emailstring<email>required
rolestringmemberadmin

Response

201Createdobject

Created invite

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create an account invite
curl -X POST 'https://api.nitrosend.com/v1/my/account/invites' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "role": "member"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "email": "user@example.com",
      "role": "member"
    }),
});

const data = await response.json();
import requests

payload = {
  "email": "user@example.com",
  "role": "member"
}

response = requests.post('https://api.nitrosend.com/v1/my/account/invites', json=payload)
data = response.json()
Request Body
{
  "email": "user@example.com",
  "role": "member"
}
{
  "id": 0,
  "account_id": 0,
  "email": "user@example.com",
  "role": "member",
  "token": "string",
  "status": "pending",
  "accepted_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Revoke an invite

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

Parameters

idintegerrequiredpath

Response

200OKobject

Revoked invite

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Revoke an invite
curl -X DELETE 'https://api.nitrosend.com/v1/my/account/invites/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/account/invites/{id}')
data = response.json()
200
{
  "id": 0,
  "account_id": 0,
  "email": "user@example.com",
  "role": "member",
  "token": "string",
  "status": "pending",
  "accepted_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Accept an invite token

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

Parameters

idstringrequiredpath

Response

200OKobject

Accepted invite

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Accept an invite token
curl -X POST 'https://api.nitrosend.com/v1/my/account/invites/{id}/accept'
const response = await fetch('https://api.nitrosend.com/v1/my/account/invites/{id}/accept', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/account/invites/{id}/accept')
data = response.json()
{
  "id": 0,
  "account_id": 0,
  "email": "user@example.com",
  "role": "member",
  "token": "string",
  "status": "pending",
  "accepted_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Contacts

Contact management

List contacts (paginated)

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

Parameters

pageinteger1query
limitinteger50query
searchstringquery

Full-text search across name, email, phone

list_idintegerquery

Filter contacts belonging to this list

tagstringquery

Filter contacts that have this tag. Tags are stored as an array of strings under data.tags. Only one tag filter is supported here; for more complex tag-based targeting, create a Segment with the contact_tag filter and the cont predicate.

Response

200OKArray<object>

Paginated contacts

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List contacts (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/contacts'
const response = await fetch('https://api.nitrosend.com/v1/my/contacts', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/contacts')
data = response.json()
200
[
  {
    "id": 0,
    "brand_id": 0,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "string",
    "last_name": "string",
    "source": "string",
    "country_code": "string",
    "data": {
      "tags": [
        "vip",
        "newsletter"
      ],
      "plan": "pro"
    },
    "subscribed_phone": true,
    "subscribed_email": true,
    "verification_status": "verified",
    "enrichment_status": "enriched",
    "list_ids": [
      0
    ],
    "last_interacted_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "channels": [
      {
        "id": 0,
        "contact_id": 0,
        "kind": "email",
        "value": "string",
        "subscribed": true,
        "verified": true,
        "opt_in_at": "2024-01-15T09:30:00Z",
        "opt_out_at": "2024-01-15T09:30:00Z",
        "sent_count": 0,
        "fail_count": 0,
        "data": {},
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ]
  }
]

Create a contact

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

Body

application/json
first_namestring
last_namestring
emailstring<email>

Creates/updates email channel with opt_in

phonestring

E.164 format. Creates/updates phone channel with opt_in

sourcestring
country_codestring
list_idsArray<integer>
dataobject

Custom key-value data. The reserved key tags holds an array of string labels used for segmentation — e.g. {"tags": ["vip", "newsletter"]}. Writing data.tags replaces the contact's existing tag list.

channels_attributesArray<object>
Show child attributes
kindstringemailphone
valuestring
subscribedboolean

Response

201Createdobject

Contact created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a contact
curl -X POST 'https://api.nitrosend.com/v1/my/contacts' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "phone": "string",
    "source": "string",
    "country_code": "string",
    "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: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "phone": "string",
      "source": "string",
      "country_code": "string",
      "list_ids": [
        0
      ],
      "data": {
        "tags": [
          "vip",
          "newsletter"
        ],
        "plan": "pro"
      },
      "channels_attributes": [
        {
          "kind": "email",
          "value": "string",
          "subscribed": true
        }
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "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', json=payload)
data = response.json()
Request Body
{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "kind": "email",
      "value": "string",
      "subscribed": true
    }
  ]
}
{
  "id": 0,
  "brand_id": 0,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "string",
  "last_name": "string",
  "source": "string",
  "country_code": "string",
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "subscribed_phone": true,
  "subscribed_email": true,
  "verification_status": "verified",
  "enrichment_status": "enriched",
  "list_ids": [
    0
  ],
  "last_interacted_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "channels": [
    {
      "id": 0,
      "contact_id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "verified": true,
      "opt_in_at": "2024-01-15T09:30:00Z",
      "opt_out_at": "2024-01-15T09:30:00Z",
      "sent_count": 0,
      "fail_count": 0,
      "data": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a contact

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

Parameters

idintegerrequiredpath

Response

200OKobject

Contact with channels

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a contact
curl -X GET 'https://api.nitrosend.com/v1/my/contacts/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/contacts/{id}')
data = response.json()
{
  "id": 0,
  "brand_id": 0,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "string",
  "last_name": "string",
  "source": "string",
  "country_code": "string",
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "subscribed_phone": true,
  "subscribed_email": true,
  "verification_status": "verified",
  "enrichment_status": "enriched",
  "list_ids": [
    0
  ],
  "last_interacted_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "channels": [
    {
      "id": 0,
      "contact_id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "verified": true,
      "opt_in_at": "2024-01-15T09:30:00Z",
      "opt_out_at": "2024-01-15T09:30:00Z",
      "sent_count": 0,
      "fail_count": 0,
      "data": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete a contact

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

Parameters

idintegerrequiredpath

Response

200OKobject

Deleted contact

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete a contact
curl -X DELETE 'https://api.nitrosend.com/v1/my/contacts/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/contacts/{id}')
data = response.json()
200
{
  "id": 0,
  "brand_id": 0,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "string",
  "last_name": "string",
  "source": "string",
  "country_code": "string",
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "subscribed_phone": true,
  "subscribed_email": true,
  "verification_status": "verified",
  "enrichment_status": "enriched",
  "list_ids": [
    0
  ],
  "last_interacted_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "channels": [
    {
      "id": 0,
      "contact_id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "verified": true,
      "opt_in_at": "2024-01-15T09:30:00Z",
      "opt_out_at": "2024-01-15T09:30:00Z",
      "sent_count": 0,
      "fail_count": 0,
      "data": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

Update a contact

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

Body

application/json
first_namestring
last_namestring
emailstring<email>
phonestring
sourcestring
country_codestring
list_idsArray<integer>
dataobject

Custom key-value data. The reserved key tags holds an array of string labels used for segmentation — e.g. {"tags": ["vip", "newsletter"]}.

The data object is replaced wholesale on update. Sending a partial data hash will overwrite any other keys currently stored (e.g. data.plan, enrichment metadata). To change a single key, GET the contact, merge your change into the existing data, then PATCH the full merged object back. For add/remove tag semantics across many contacts, use the nitro_manage_audience MCP tool with operation: "bulk_tag".

channels_attributesArray<object>
Show child attributes
idinteger
kindstringemailphone
valuestring
subscribedboolean
_destroyboolean

Parameters

idintegerrequiredpath

Response

200OKobject

Updated contact

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a contact
curl -X PATCH 'https://api.nitrosend.com/v1/my/contacts/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "phone": "string",
    "source": "string",
    "country_code": "string",
    "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/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "phone": "string",
      "source": "string",
      "country_code": "string",
      "list_ids": [
        0
      ],
      "data": {
        "tags": [
          "vip",
          "newsletter"
        ],
        "plan": "pro"
      },
      "channels_attributes": [
        {
          "id": 0,
          "kind": "email",
          "value": "string",
          "subscribed": true,
          "_destroy": true
        }
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "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/{id}', json=payload)
data = response.json()
Request Body
{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "string",
  "source": "string",
  "country_code": "string",
  "list_ids": [
    0
  ],
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "channels_attributes": [
    {
      "id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "_destroy": true
    }
  ]
}
{
  "id": 0,
  "brand_id": 0,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "string",
  "last_name": "string",
  "source": "string",
  "country_code": "string",
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "subscribed_phone": true,
  "subscribed_email": true,
  "verification_status": "verified",
  "enrichment_status": "enriched",
  "list_ids": [
    0
  ],
  "last_interacted_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "channels": [
    {
      "id": 0,
      "contact_id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "verified": true,
      "opt_in_at": "2024-01-15T09:30:00Z",
      "opt_out_at": "2024-01-15T09:30:00Z",
      "sent_count": 0,
      "fail_count": 0,
      "data": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Re-enrich a contact via email verification + Apollo

POST
https://api.nitrosend.com/v1/my/contacts/{id}/enrich

Queues the contact for email verification and Apollo enrichment. Consumes 2 validation allowance units. Requires the contact to have an email channel.

Parameters

idintegerrequiredpath

Response

200OKobject

Enrichment queued

400Bad Request

Contact has no email or validation allowance exhausted

401Unauthorizedobject

Not authenticated

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Re-enrich a contact via email verification + Apollo
curl -X POST 'https://api.nitrosend.com/v1/my/contacts/{id}/enrich'
const response = await fetch('https://api.nitrosend.com/v1/my/contacts/{id}/enrich', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/contacts/{id}/enrich')
data = response.json()
{
  "id": 0,
  "brand_id": 0,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "string",
  "last_name": "string",
  "source": "string",
  "country_code": "string",
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "subscribed_phone": true,
  "subscribed_email": true,
  "verification_status": "verified",
  "enrichment_status": "enriched",
  "list_ids": [
    0
  ],
  "last_interacted_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "channels": [
    {
      "id": 0,
      "contact_id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "verified": true,
      "opt_in_at": "2024-01-15T09:30:00Z",
      "opt_out_at": "2024-01-15T09:30:00Z",
      "sent_count": 0,
      "fail_count": 0,
      "data": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Imports

Bulk CSV import jobs

List import jobs

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

Parameters

pageinteger1query
limitinteger25query

Response

200OKArray<object>

Paginated import jobs

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List import jobs
curl -X GET 'https://api.nitrosend.com/v1/my/imports'
const response = await fetch('https://api.nitrosend.com/v1/my/imports', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/imports')
data = response.json()
200
[
  {
    "id": 0,
    "resource": "contacts",
    "parser": "default",
    "status": "pending",
    "total_rows": 0,
    "success_rows": 0,
    "failed_rows": 0,
    "import_errors": [
      [
        0
      ]
    ],
    "columns": {},
    "options": {},
    "started_at": "2024-01-15T09:30:00Z",
    "ended_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z"
  }
]

Start a CSV import

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

Uploads a CSV file and enqueues an import job. 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]}.

Body

multipart/form-data
filestring<binary>required

CSV file, maximum 10 MB

resourcestringcontactscontacts
parserstringdefaultdefault
dry_runbooleanfalse
columnsobject | string

CSV column mapping as a JSON object or JSON string.

optionsobject | string

Import options as a JSON object or JSON string.

Response

201Createdobject

Import queued

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Start a CSV import
curl -X POST 'https://api.nitrosend.com/v1/my/imports' \
  -H 'Content-Type: multipart/form-data' \
  -d '{
    "file": "<binary>",
    "resource": "contacts",
    "parser": "default",
    "dry_run": false,
    "columns": {
      "email": "Email",
      "first_name": "First Name"
    },
    "options": {
      "list_ids": [
        88
      ]
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/imports', {
  method: 'POST',
  headers: {
    'Content-Type': 'multipart/form-data',
  },
  body: JSON.stringify({
      "file": "<binary>",
      "resource": "contacts",
      "parser": "default",
      "dry_run": false,
      "columns": {
        "email": "Email",
        "first_name": "First Name"
      },
      "options": {
        "list_ids": [
          88
        ]
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "file": "<binary>",
  "resource": "contacts",
  "parser": "default",
  "dry_run": False,
  "columns": {
    "email": "Email",
    "first_name": "First Name"
  },
  "options": {
    "list_ids": [
      88
    ]
  }
}

response = requests.post('https://api.nitrosend.com/v1/my/imports', json=payload)
data = response.json()
Request Body
{
  "file": "<binary>",
  "resource": "contacts",
  "parser": "default",
  "dry_run": false,
  "columns": {
    "email": "Email",
    "first_name": "First Name"
  },
  "options": {
    "list_ids": [
      88
    ]
  }
}
{
  "id": 0,
  "resource": "contacts",
  "parser": "default",
  "status": "pending",
  "total_rows": 0,
  "success_rows": 0,
  "failed_rows": 0,
  "import_errors": [
    [
      0
    ]
  ],
  "columns": {},
  "options": {},
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get import schema metadata

GET
https://api.nitrosend.com/v1/my/imports/spec

Parameters

resourcestringcontactsquery

Optional resource name. Omit to list all schemas.

Response

200OKobject

Import schema metadata

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get import schema metadata
curl -X GET 'https://api.nitrosend.com/v1/my/imports/spec'
const response = await fetch('https://api.nitrosend.com/v1/my/imports/spec', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/imports/spec')
data = response.json()
{}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get import job status

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

Parameters

idintegerrequiredpath

Response

200OKobject

Import job with status, counts, and row errors

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get import job status
curl -X GET 'https://api.nitrosend.com/v1/my/imports/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/imports/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/imports/{id}')
data = response.json()
{
  "id": 0,
  "resource": "contacts",
  "parser": "default",
  "status": "pending",
  "total_rows": 0,
  "success_rows": 0,
  "failed_rows": 0,
  "import_errors": [
    [
      0
    ]
  ],
  "columns": {},
  "options": {},
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete an import record

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

Parameters

idintegerrequiredpath

Response

200OKobject

Deleted import

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete an import record
curl -X DELETE 'https://api.nitrosend.com/v1/my/imports/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/imports/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/imports/{id}')
data = response.json()
{
  "id": 0,
  "resource": "contacts",
  "parser": "default",
  "status": "pending",
  "total_rows": 0,
  "success_rows": 0,
  "failed_rows": 0,
  "import_errors": [
    [
      0
    ]
  ],
  "columns": {},
  "options": {},
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Cancel a pending or processing import

POST
https://api.nitrosend.com/v1/my/imports/{id}/cancel

Parameters

idintegerrequiredpath

Response

200OKobject

Canceled import

404Not Foundobject

Resource not found

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Cancel a pending or processing import
curl -X POST 'https://api.nitrosend.com/v1/my/imports/{id}/cancel'
const response = await fetch('https://api.nitrosend.com/v1/my/imports/{id}/cancel', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/imports/{id}/cancel')
data = response.json()
{
  "id": 0,
  "resource": "contacts",
  "parser": "default",
  "status": "pending",
  "total_rows": 0,
  "success_rows": 0,
  "failed_rows": 0,
  "import_errors": [
    [
      0
    ]
  ],
  "columns": {},
  "options": {},
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Lists

Contact lists

List contact lists (paginated)

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

Parameters

namestringquery

Exact case-insensitive list name filter

pageinteger1query
limitinteger25query

Response

200OKArray<object>

Paginated contact lists

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List contact lists (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/lists'
const response = await fetch('https://api.nitrosend.com/v1/my/lists', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/lists')
data = response.json()
200
[
  {
    "id": 0,
    "account_id": 0,
    "brand_id": 0,
    "name": "string",
    "contacts_count": 0,
    "segment_id": 0,
    "stale": true,
    "last_populated_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Create a contact list

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

Body

application/json
namestringrequired
segment_idinteger | null
contact_idsArray<integer>

Response

201Createdobject

List created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a contact list
curl -X POST 'https://api.nitrosend.com/v1/my/lists' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "segment_id": 0,
    "contact_ids": [
      0
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/lists', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "segment_id": 0,
      "contact_ids": [
        0
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}

response = requests.post('https://api.nitrosend.com/v1/my/lists', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "contacts_count": 0,
  "segment_id": 0,
  "stale": true,
  "last_populated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a contact list

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

Parameters

idintegerrequiredpath

Response

200OKobject

Contact list

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a contact list
curl -X GET 'https://api.nitrosend.com/v1/my/lists/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/lists/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/lists/{id}')
data = response.json()
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "contacts_count": 0,
  "segment_id": 0,
  "stale": true,
  "last_populated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete a contact list

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

Parameters

idintegerrequiredpath

Response

200OKobject

Deleted list

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete a contact list
curl -X DELETE 'https://api.nitrosend.com/v1/my/lists/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/lists/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/lists/{id}')
data = response.json()
200
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "contacts_count": 0,
  "segment_id": 0,
  "stale": true,
  "last_populated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Update a contact list

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

Body

application/json
namestring
segment_idinteger | null
contact_idsArray<integer>

Parameters

idintegerrequiredpath

Response

200OKobject

Updated list

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a contact list
curl -X PATCH 'https://api.nitrosend.com/v1/my/lists/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "segment_id": 0,
    "contact_ids": [
      0
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/lists/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "segment_id": 0,
      "contact_ids": [
        0
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}

response = requests.patch('https://api.nitrosend.com/v1/my/lists/{id}', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "segment_id": 0,
  "contact_ids": [
    0
  ]
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "contacts_count": 0,
  "segment_id": 0,
  "stale": true,
  "last_populated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get delete warning metadata for a contact list

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

Parameters

idintegerrequiredpath

Response

200OKobject

Flows connected to this list

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get delete warning metadata for a contact list
curl -X GET 'https://api.nitrosend.com/v1/my/lists/{id}/delete_warning'
const response = await fetch('https://api.nitrosend.com/v1/my/lists/{id}/delete_warning', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/lists/{id}/delete_warning')
data = response.json()
200
{
  "campaign_names": [
    "string"
  ],
  "flow_names": [
    "string"
  ]
}

Add or remove existing contacts from a list by email

POST
https://api.nitrosend.com/v1/my/lists/{id}/contacts/bulk

Public REST equivalent of the list membership batch primitive. The endpoint resolves existing contacts by email within the current brand and adds or removes memberships idempotently. It does not create contacts; emails with no current-brand contact are returned in not_found.

Body

application/json
actionstringaddremoverequired

Add existing contacts to the list or remove them from it.

emailsArray<string>required

Parameters

idintegerrequiredpath

Response

200OKobject

Bulk list membership result

404Not Foundobject

Resource not found

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Add or remove existing contacts from a list by email
curl -X POST 'https://api.nitrosend.com/v1/my/lists/{id}/contacts/bulk' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "add",
    "emails": [
      "user@example.com"
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/lists/{id}/contacts/bulk', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "action": "add",
      "emails": [
        "user@example.com"
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "action": "add",
  "emails": [
    "user@example.com"
  ]
}

response = requests.post('https://api.nitrosend.com/v1/my/lists/{id}/contacts/bulk', json=payload)
data = response.json()
Request Body
{
  "action": "add",
  "emails": [
    "user@example.com"
  ]
}
{
  "action": "add",
  "list_id": 0,
  "added": 0,
  "removed": 0,
  "already_in_list": [
    "user@example.com"
  ],
  "not_in_list": [
    "user@example.com"
  ],
  "not_found": [
    "user@example.com"
  ],
  "invalid_emails": [
    "string"
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Segments

Dynamic contact segments

List all segments

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

Response

200OKArray<object>

Segments

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List all segments
curl -X GET 'https://api.nitrosend.com/v1/my/segments'
const response = await fetch('https://api.nitrosend.com/v1/my/segments', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/segments')
data = response.json()
200
[
  {
    "id": 0,
    "account_id": 0,
    "brand_id": 0,
    "name": "string",
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ],
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Create a segment

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

Body

application/json
namestringrequired
filtersArray<object>
Show child attributes
namestringrequired

Filter name from flows.yml: 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

predicatestringrequired

Ransack predicate: eq, not_eq, cont, not_cont, start, end, gt, lt, gteq, lteq, present, blank, true, false, in, not_in

valueanyrequired

Filter value — string, number, boolean, or array for in/not_in

Response

201Createdobject

Segment created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a segment
curl -X POST 'https://api.nitrosend.com/v1/my/segments' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/segments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}

response = requests.post('https://api.nitrosend.com/v1/my/segments', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a segment

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

Parameters

idintegerrequiredpath

Response

200OKobject

Segment

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a segment
curl -X GET 'https://api.nitrosend.com/v1/my/segments/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/segments/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/segments/{id}')
data = response.json()
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete a segment

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

Parameters

idintegerrequiredpath

Response

200OKobject

Deleted segment

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete a segment
curl -X DELETE 'https://api.nitrosend.com/v1/my/segments/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/segments/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/segments/{id}')
data = response.json()
200
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Update a segment

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

Body

application/json
namestring
filtersArray<object>
Show child attributes
namestringrequired

Filter name from flows.yml: 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

predicatestringrequired

Ransack predicate: eq, not_eq, cont, not_cont, start, end, gt, lt, gteq, lteq, present, blank, true, false, in, not_in

valueanyrequired

Filter value — string, number, boolean, or array for in/not_in

Parameters

idintegerrequiredpath

Response

200OKobject

Updated segment

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a segment
curl -X PATCH 'https://api.nitrosend.com/v1/my/segments/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/segments/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}

response = requests.patch('https://api.nitrosend.com/v1/my/segments/{id}', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Count contacts matching filters

POST
https://api.nitrosend.com/v1/my/segments/count

Preview how many contacts match a set of segment filters without creating or saving a segment.

Body

application/json
filtersArray<object>
Show child attributes
namestringrequired

Filter name from flows.yml: 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

predicatestringrequired

Ransack predicate: eq, not_eq, cont, not_cont, start, end, gt, lt, gteq, lteq, present, blank, true, false, in, not_in

valueanyrequired

Filter value — string, number, boolean, or array for in/not_in

Response

200OKobject

Contact count

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Count contacts matching filters
curl -X POST 'https://api.nitrosend.com/v1/my/segments/count' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
      {
        "name": "string",
        "predicate": "string"
      }
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/segments/count', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "filters": [
        {
          "name": "string",
          "predicate": "string"
        }
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}

response = requests.post('https://api.nitrosend.com/v1/my/segments/count', json=payload)
data = response.json()
Request Body
{
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ]
}
200
{
  "count": 0
}

Campaigns

Email and SMS campaigns

List campaigns (paginated)

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

Parameters

pageinteger1query
limitinteger25query

Response

200OKArray<object>

Paginated campaigns

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List campaigns (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/campaigns')
data = response.json()
200
[
  {
    "id": 0,
    "account_id": 0,
    "brand_id": 0,
    "status": "draft",
    "approval_state": "string",
    "channel": "email",
    "name": "string",
    "data": {},
    "scheduled_at": "2024-01-15T09:30:00Z",
    "sent_count": 0,
    "editable": true,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "trigger": {
      "id": 0,
      "flow_id": 0,
      "event": "string",
      "audience_type": "lists",
      "segment_id": 0,
      "contact_list_id": 0,
      "contact_list_ids": [
        0
      ],
      "data": {},
      "triggered_count": 0,
      "last_triggered_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    },
    "template": {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    },
    "templates": [
      {
        "id": 0,
        "name": "string",
        "flow_id": 0,
        "action_id": 0,
        "subject": "string",
        "body": "string",
        "preheader": "string",
        "from_name": "string",
        "from_email": "string",
        "reply_to": "string",
        "design": {
          "sections": [
            {
              "type": "header",
              "props": {},
              "styles": {
                "background_color": "string",
                "padding": "string",
                "align": "left"
              }
            }
          ],
          "theme": {
            "brand_color": "string",
            "bg_color": "string",
            "text_color": "string",
            "font_body": "string",
            "font_heading": "string",
            "logo_url": "string"
          }
        },
        "variables": {},
        "generation_id": 0,
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ]
  }
]

Create a campaign

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

Body

application/json
namestringrequired
channelstringemailsmsemail

Response

201Createdobject

Campaign created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a campaign
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "channel": "email"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "channel": "email"
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "channel": "email"
}

response = requests.post('https://api.nitrosend.com/v1/my/campaigns', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "channel": "email"
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a campaign

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

Parameters

idintegerrequiredpath

Response

200OKobject

Campaign with trigger, template, and templates

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a campaign
curl -X GET 'https://api.nitrosend.com/v1/my/campaigns/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/campaigns/{id}')
data = response.json()
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete a campaign

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

Parameters

idintegerrequiredpath

Response

200OKobject

Deleted campaign

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete a campaign
curl -X DELETE 'https://api.nitrosend.com/v1/my/campaigns/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/campaigns/{id}')
data = response.json()
200
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

Update a campaign

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

Updates the campaign. When the campaign is no longer editable (see the editable field on the Campaign schema — false for live/paused/ completed/cancelled/archived, and for scheduled campaigns within 5 minutes of their send time), only name-only payloads and status transitions (Resume, Cancel) are accepted. Any other attribute returns 422 with error_code: "campaign_locked". Use the /duplicate endpoint to fork a sent campaign into a new draft.

Body

application/json
namestring
statusstring
channelstringemailsms
scheduled_atstring<date-time> | null
trigger_attributesobject
Show child attributes
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target. Use all_contacts only for deliberate all-subscribed-contact sends.

contact_list_idinteger | nulldeprecated
contact_list_idsArray<integer>
segment_idinteger | null
dataobject
template_attributesobject
Show child attributes
subjectstring
bodystring
preheaderstring
from_namestring
from_emailstring<email>
reply_tostring<email>
designobject

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring

Parameters

idintegerrequiredpath

Response

200OKobject

Updated campaign

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a campaign
curl -X PATCH 'https://api.nitrosend.com/v1/my/campaigns/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "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,
      "data": {}
    },
    "template_attributes": {
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "user@example.com",
      "reply_to": "user@example.com",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      }
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "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,
        "data": {}
      },
      "template_attributes": {
        "subject": "string",
        "body": "string",
        "preheader": "string",
        "from_name": "string",
        "from_email": "user@example.com",
        "reply_to": "user@example.com",
        "design": {
          "sections": [
            {
              "type": "header",
              "props": {},
              "styles": {
                "background_color": "string",
                "padding": "string",
                "align": "left"
              }
            }
          ],
          "theme": {
            "brand_color": "string",
            "bg_color": "string",
            "text_color": "string",
            "font_body": "string",
            "font_heading": "string",
            "logo_url": "string"
          }
        }
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "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,
    "data": {}
  },
  "template_attributes": {
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }
}

response = requests.patch('https://api.nitrosend.com/v1/my/campaigns/{id}', json=payload)
data = response.json()
Request 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,
    "data": {}
  },
  "template_attributes": {
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Duplicate a campaign

POST
https://api.nitrosend.com/v1/my/campaigns/{id}/duplicate

Creates a new draft campaign that copies the source's audience (trigger.audience_type, contact_list_ids, segment_id) and template content (design, subject, preheader, body, from_name, from_email, reply_to). Resets status to draft, approval_state to pending_review, scheduled_at to null, and trigger.event to manual. Works on any status — this is how clients fork a sent campaign into a new draft. Sessions, activities, approvals, and metrics are not copied.

Pass cancel_source: true to atomically cancel the source campaign in the same transaction as the duplicate — useful for 'cancel and duplicate' flows on paused campaigns.

Body

application/json
cancel_sourcebooleanfalse

When true, cancels the source campaign in the same DB transaction as the duplicate creation.

Parameters

idintegerrequiredpath

Response

201Createdobject

New draft campaign

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Duplicate a campaign
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns/{id}/duplicate' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancel_source": false
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/{id}/duplicate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "cancel_source": false
    }),
});

const data = await response.json();
import requests

payload = {
  "cancel_source": False
}

response = requests.post('https://api.nitrosend.com/v1/my/campaigns/{id}/duplicate', json=payload)
data = response.json()
Request Body
{
  "cancel_source": false
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Send a campaign

POST
https://api.nitrosend.com/v1/my/campaigns/{id}/send

Transitions the campaign and its flow to live, then delivers. Optionally update trigger and template attributes in the same request. Returns 422 campaign_locked if the campaign is not editable (live, paused, completed, cancelled, archived, or scheduled within 5 minutes of send).

Body

application/json
confirm_send_to_allboolean

Required when trigger_attributes.audience_type or the saved trigger audience_type is all_contacts.

trigger_attributesobject
Show child attributes
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target. Use all_contacts only for deliberate all-subscribed-contact sends.

contact_list_idinteger | nulldeprecated
contact_list_idsArray<integer>
segment_idinteger | null
dataobject
template_attributesobject
Show child attributes
subjectstring
bodystring
preheaderstring
from_namestring
from_emailstring<email>
reply_tostring<email>
designobject

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring

Parameters

idintegerrequiredpath

Response

200OKobject

Campaign sent

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Send a campaign
curl -X POST 'https://api.nitrosend.com/v1/my/campaigns/{id}/send' \
  -H 'Content-Type: application/json' \
  -d '{
    "confirm_send_to_all": true,
    "trigger_attributes": {
      "event": "string",
      "audience_type": "lists",
      "contact_list_id": 0,
      "contact_list_ids": [
        0
      ],
      "segment_id": 0,
      "data": {}
    },
    "template_attributes": {
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "user@example.com",
      "reply_to": "user@example.com",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      }
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/campaigns/{id}/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "confirm_send_to_all": true,
      "trigger_attributes": {
        "event": "string",
        "audience_type": "lists",
        "contact_list_id": 0,
        "contact_list_ids": [
          0
        ],
        "segment_id": 0,
        "data": {}
      },
      "template_attributes": {
        "subject": "string",
        "body": "string",
        "preheader": "string",
        "from_name": "string",
        "from_email": "user@example.com",
        "reply_to": "user@example.com",
        "design": {
          "sections": [
            {
              "type": "header",
              "props": {},
              "styles": {
                "background_color": "string",
                "padding": "string",
                "align": "left"
              }
            }
          ],
          "theme": {
            "brand_color": "string",
            "bg_color": "string",
            "text_color": "string",
            "font_body": "string",
            "font_heading": "string",
            "logo_url": "string"
          }
        }
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "confirm_send_to_all": True,
  "trigger_attributes": {
    "event": "string",
    "audience_type": "lists",
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "segment_id": 0,
    "data": {}
  },
  "template_attributes": {
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }
}

response = requests.post('https://api.nitrosend.com/v1/my/campaigns/{id}/send', json=payload)
data = response.json()
Request Body
{
  "confirm_send_to_all": true,
  "trigger_attributes": {
    "event": "string",
    "audience_type": "lists",
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "segment_id": 0,
    "data": {}
  },
  "template_attributes": {
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }
}
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Messages

Transactional email and SMS messages

List messages

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

Returns transactional messages by default. Use source_type=all to include flow/campaign-generated messages, or source_type=flow for flow-only.

Parameters

source_typestringallflowquery

Filter by source. Omit for transactional only, 'all' for everything, 'flow' for flow/campaign messages.

channelstringemailsmsquery
statusstringqueuedsentfailedquery
pageinteger1query
limitinteger25query

Response

200OKArray<object>

Paginated list of messages

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List messages
curl -X GET 'https://api.nitrosend.com/v1/my/messages'
const response = await fetch('https://api.nitrosend.com/v1/my/messages', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/messages')
data = response.json()
200
[
  {
    "id": 0,
    "channel": "email",
    "to": "string",
    "subject": "string",
    "status": "queued",
    "provider_id": "string",
    "flow_id": 0,
    "source_type": "campaign",
    "source_name": "string",
    "sent_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z"
  }
]

Send a transactional message

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

Send a transactional email or SMS to a single recipient immediately. No campaign, no audience, no approval required. Use for receipts, password resets, OTPs, order confirmations, and system notifications.

Body

application/json
channelstringemailsmsrequired
tostringrequired

Recipient email address or E.164 phone number

subjectstring

Email subject line (required for email channel)

bodystring

Message body. Required for SMS. Optional plain text for email.

template_idinteger

Load email design from an existing template (email only)

dataobject

Merge variables

idempotency_keystring

Idempotency key (alternative to header)

Parameters

Idempotency-Keystringheader

Prevents duplicate sends on retry. Same key returns the original message.

Response

201Createdobject

Message created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Send a transactional message
curl -X POST 'https://api.nitrosend.com/v1/my/messages' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "email",
    "to": "string",
    "subject": "string",
    "body": "string",
    "template_id": 0,
    "data": {},
    "idempotency_key": "string"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "channel": "email",
      "to": "string",
      "subject": "string",
      "body": "string",
      "template_id": 0,
      "data": {},
      "idempotency_key": "string"
    }),
});

const data = await response.json();
import requests

payload = {
  "channel": "email",
  "to": "string",
  "subject": "string",
  "body": "string",
  "template_id": 0,
  "data": {},
  "idempotency_key": "string"
}

response = requests.post('https://api.nitrosend.com/v1/my/messages', json=payload)
data = response.json()
Request Body
{
  "channel": "email",
  "to": "string",
  "subject": "string",
  "body": "string",
  "template_id": 0,
  "data": {},
  "idempotency_key": "string"
}
{
  "id": 0,
  "channel": "email",
  "to": "string",
  "subject": "string",
  "status": "queued",
  "provider_id": "string",
  "flow_id": 0,
  "source_type": "campaign",
  "source_name": "string",
  "sent_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a transactional message

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

Parameters

idintegerrequiredpath

Response

200OKobject

Message

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a transactional message
curl -X GET 'https://api.nitrosend.com/v1/my/messages/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/messages/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/messages/{id}')
data = response.json()
{
  "id": 0,
  "channel": "email",
  "to": "string",
  "subject": "string",
  "status": "queued",
  "provider_id": "string",
  "flow_id": 0,
  "source_type": "campaign",
  "source_name": "string",
  "sent_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Templates

Email templates, preview, and component schema

List all templates

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

Returns a summary view with section counts (not full design).

Response

200OKArray<object>

Template summaries

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List all templates
curl -X GET 'https://api.nitrosend.com/v1/my/templates'
const response = await fetch('https://api.nitrosend.com/v1/my/templates', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/templates')
data = response.json()
200
[
  {
    "id": 0,
    "name": "string",
    "subject": "string",
    "preheader": "string",
    "flow_id": 0,
    "section_count": 0,
    "section_types": [
      "string"
    ],
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Create a standalone template

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

Body

application/json
namestringrequired
subjectstring
preheaderstring
generation_idinteger | null
designobject

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring

Response

201Createdobject

Created template

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a standalone template
curl -X POST 'https://api.nitrosend.com/v1/my/templates' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "subject": "string",
    "preheader": "string",
    "generation_id": 0,
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/templates', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "subject": "string",
      "preheader": "string",
      "generation_id": 0,
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "subject": "string",
  "preheader": "string",
  "generation_id": 0,
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  }
}

response = requests.post('https://api.nitrosend.com/v1/my/templates', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "subject": "string",
  "preheader": "string",
  "generation_id": 0,
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  }
}
{
  "id": 0,
  "name": "string",
  "flow_id": 0,
  "action_id": 0,
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "string",
  "reply_to": "string",
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  },
  "variables": {},
  "generation_id": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a template with full design

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

Parameters

idintegerrequiredpath

Response

200OKobject

Full template including design

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a template with full design
curl -X GET 'https://api.nitrosend.com/v1/my/templates/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/templates/{id}')
data = response.json()
{
  "id": 0,
  "name": "string",
  "flow_id": 0,
  "action_id": 0,
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "string",
  "reply_to": "string",
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  },
  "variables": {},
  "generation_id": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Update a template

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

Body

application/json
namestring
subjectstring
bodystring
preheaderstring
from_namestring
from_emailstring<email>
reply_tostring<email>
generation_idinteger | null
designobject

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring

Parameters

idintegerrequiredpath

Response

200OKobject

Updated template

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a template
curl -X PATCH 'https://api.nitrosend.com/v1/my/templates/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "user@example.com",
    "reply_to": "user@example.com",
    "generation_id": 0,
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "user@example.com",
      "reply_to": "user@example.com",
      "generation_id": 0,
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "user@example.com",
  "reply_to": "user@example.com",
  "generation_id": 0,
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  }
}

response = requests.patch('https://api.nitrosend.com/v1/my/templates/{id}', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "user@example.com",
  "reply_to": "user@example.com",
  "generation_id": 0,
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  }
}
{
  "id": 0,
  "name": "string",
  "flow_id": 0,
  "action_id": 0,
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "string",
  "reply_to": "string",
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  },
  "variables": {},
  "generation_id": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Send a test email

POST
https://api.nitrosend.com/v1/my/templates/{id}/send_test

Send a test email for the given template. Provide email for an explicit recipient, contact_id to use a contact's email (with merge-tag personalization), or omit both to send to the account owner.

Body

application/json
emailstring<email>
contact_idinteger

Parameters

idintegerrequiredpath

Response

200OKobject

Test email sent

404Not Foundobject

Resource not found

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Send a test email
curl -X POST 'https://api.nitrosend.com/v1/my/templates/{id}/send_test' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "contact_id": 0
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/{id}/send_test', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "email": "user@example.com",
      "contact_id": 0
    }),
});

const data = await response.json();
import requests

payload = {
  "email": "user@example.com",
  "contact_id": 0
}

response = requests.post('https://api.nitrosend.com/v1/my/templates/{id}/send_test', json=payload)
data = response.json()
Request Body
{
  "email": "user@example.com",
  "contact_id": 0
}
{
  "sent": 0,
  "results": [
    {
      "email": "string",
      "success": true
    }
  ]
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Render an email design to HTML

POST
https://api.nitrosend.com/v1/my/templates/preview

Body

application/json
documentobjectrequired

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring

Response

200OKobject

Rendered HTML

400Bad Requestobject

Bad request

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Render an email design to HTML
curl -X POST 'https://api.nitrosend.com/v1/my/templates/preview' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/preview', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "document": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "document": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  }
}

response = requests.post('https://api.nitrosend.com/v1/my/templates/preview', json=payload)
data = response.json()
Request Body
{
  "document": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  }
}
{
  "html": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Get the email component schema

GET
https://api.nitrosend.com/v1/my/templates/spec

Returns the full schema for email design sections including all component types, their props, required fields, and defaults. Sourced from config/email_components.yml.

Response

200OKobject

Email component schema

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get the email component schema
curl -X GET 'https://api.nitrosend.com/v1/my/templates/spec'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/spec', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/templates/spec')
data = response.json()
200
{
  "version": 0,
  "design_guidelines": "string",
  "components": [
    {
      "type": "string",
      "description": "string",
      "tips": [
        "string"
      ],
      "props": {}
    }
  ],
  "common_styles": {},
  "variables": [
    "string"
  ],
  "theme_fields": [
    "string"
  ]
}

List email starter designs

GET
https://api.nitrosend.com/v1/my/templates/starters

Returns config-based starter email designs with the current brand's theme merged and an HTML preview rendered for each starter.

Response

200OKArray<object>

Starter designs with brand theme and preview HTML

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List email starter designs
curl -X GET 'https://api.nitrosend.com/v1/my/templates/starters'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/starters', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/templates/starters')
data = response.json()
200
[
  {
    "id": "string",
    "category": "string",
    "name": "string",
    "description": "string",
    "icon": "string",
    "suggested_goals": [
      "string"
    ],
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "preview_html": "string"
  }
]

AI-generate an email template

POST
https://api.nitrosend.com/v1/my/templates/generate

Generate a complete email design from a text goal using AI. Returns a sections-based design, subject line, preheader, and inferred category. Supports refine mode by passing existing sections[] for modification.

Body

application/json
goalstringrequired

What the email should accomplish

categorystring

Optional category hint (welcome, newsletter, promotion, etc.)

tonestring

Optional tone override (formal, casual, etc.)

sectionsArray<object>

Current sections for refine mode — LLM adjusts existing content

Response

200OKobject

Generated email design

422Unprocessable Entityobject

Validation error

429Too Many Requestsobject

Rate limit exceeded

503Service Unavailableobject

Generation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

AI-generate an email template
curl -X POST 'https://api.nitrosend.com/v1/my/templates/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "goal": "Welcome new subscribers and introduce the brand",
    "category": "string",
    "tone": "string",
    "sections": [
      {}
    ]
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/templates/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "goal": "Welcome new subscribers and introduce the brand",
      "category": "string",
      "tone": "string",
      "sections": [
        {}
      ]
    }),
});

const data = await response.json();
import requests

payload = {
  "goal": "Welcome new subscribers and introduce the brand",
  "category": "string",
  "tone": "string",
  "sections": [
    {}
  ]
}

response = requests.post('https://api.nitrosend.com/v1/my/templates/generate', json=payload)
data = response.json()
Request Body
{
  "goal": "Welcome new subscribers and introduce the brand",
  "category": "string",
  "tone": "string",
  "sections": [
    {}
  ]
}
{
  "design": {},
  "subject": "string",
  "preheader": "string",
  "category": "string",
  "prompt_version": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Flows

Automation flows and step schema

List automation flows (paginated)

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

Returns standalone flows only (excludes campaign-attached flows).

Parameters

pageinteger1query
limitinteger25query

Response

200OKArray<any>

Paginated flows

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List automation flows (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/flows'
const response = await fetch('https://api.nitrosend.com/v1/my/flows', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/flows')
data = response.json()
200
[]

Create a flow

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

Body

application/json
namestringrequired
statusstringdraftactivepausedarchived
triggerobject
Show child attributes
eventstring

Built-in: contact_add, keyword, message, list_add, list_remove, product_view, checkout, cart_add, cart_remove, cart_abandoned, browse_abandoned. Custom: any lowercase alphanumeric with underscores.

audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — use contact_list_ids

contact_list_idsArray<integer>

Contact list IDs to target

dataobject
stepsArray<any>

Response

201Createdany

Flow created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a flow
curl -X POST 'https://api.nitrosend.com/v1/my/flows' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "status": "draft",
    "trigger": {
      "event": "string",
      "audience_type": "lists",
      "segment_id": 0,
      "contact_list_id": 0,
      "contact_list_ids": [
        0
      ],
      "data": {}
    },
    "steps": []
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/flows', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "status": "draft",
      "trigger": {
        "event": "string",
        "audience_type": "lists",
        "segment_id": 0,
        "contact_list_id": 0,
        "contact_list_ids": [
          0
        ],
        "data": {}
      },
      "steps": []
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "status": "draft",
  "trigger": {
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {}
  },
  "steps": []
}

response = requests.post('https://api.nitrosend.com/v1/my/flows', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "status": "draft",
  "trigger": {
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {}
  },
  "steps": []
}
422
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a flow

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

Parameters

idintegerrequiredpath

Response

200OKany

Flow with full graph

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a flow
curl -X GET 'https://api.nitrosend.com/v1/my/flows/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/flows/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/flows/{id}')
data = response.json()
404
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete a flow

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

Parameters

idintegerrequiredpath

Response

200OKany

Deleted flow

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete a flow
curl -X DELETE 'https://api.nitrosend.com/v1/my/flows/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/flows/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/flows/{id}')
data = response.json()

Update a flow

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

Supports optimistic concurrency — pass updated_at to reject the update if the flow was modified externally.

Body

application/json
namestring
statusstringdraftactivepausedarchived
updated_atstring<date-time>

Optimistic concurrency check

triggerobject
Show child attributes
eventstring

Built-in: contact_add, keyword, message, list_add, list_remove, product_view, checkout, cart_add, cart_remove, cart_abandoned, browse_abandoned. Custom: any lowercase alphanumeric with underscores.

audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — use contact_list_ids

contact_list_idsArray<integer>

Contact list IDs to target

dataobject
stepsArray<any>

Parameters

idintegerrequiredpath

Response

200OKany

Updated flow

409Conflictobject

Conflict — flow was modified externally

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a flow
curl -X PATCH 'https://api.nitrosend.com/v1/my/flows/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "status": "draft",
    "updated_at": "2024-01-15T09:30:00Z",
    "trigger": {
      "event": "string",
      "audience_type": "lists",
      "segment_id": 0,
      "contact_list_id": 0,
      "contact_list_ids": [
        0
      ],
      "data": {}
    },
    "steps": []
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/flows/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "name": "string",
      "status": "draft",
      "updated_at": "2024-01-15T09:30:00Z",
      "trigger": {
        "event": "string",
        "audience_type": "lists",
        "segment_id": 0,
        "contact_list_id": 0,
        "contact_list_ids": [
          0
        ],
        "data": {}
      },
      "steps": []
    }),
});

const data = await response.json();
import requests

payload = {
  "name": "string",
  "status": "draft",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {}
  },
  "steps": []
}

response = requests.patch('https://api.nitrosend.com/v1/my/flows/{id}', json=payload)
data = response.json()
Request Body
{
  "name": "string",
  "status": "draft",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {}
  },
  "steps": []
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get the flow step type schema

GET
https://api.nitrosend.com/v1/my/flows/spec

Returns the schema for flow step types, trigger events, and segment filters. Sourced from config/flows.yml.

Response

200OKobject

Flow specification

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get the flow step type schema
curl -X GET 'https://api.nitrosend.com/v1/my/flows/spec'
const response = await fetch('https://api.nitrosend.com/v1/my/flows/spec', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/flows/spec')
data = response.json()
200
{
  "filters": {},
  "triggers": [
    {
      "title": "string",
      "event": "string"
    }
  ],
  "steps": [
    {
      "type": "string",
      "title": "string",
      "summary": "string",
      "params": {}
    }
  ]
}

Events

Contact event tracking

List events (paginated)

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

Parameters

pageinteger1query
limitinteger50query
eventstringquery

Filter by event type

contact_idintegerquery
created_afterstring<date-time>query
created_beforestring<date-time>query
resource_uidstringquery
resource_namestringquery
testbooleanquery

Response

200OKArray<object>

Paginated events

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List events (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/events'
const response = await fetch('https://api.nitrosend.com/v1/my/events', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/events')
data = response.json()
200
[
  {
    "id": 0,
    "account_id": 0,
    "contact_id": 0,
    "user_id": 0,
    "event": "string",
    "amount": 0,
    "data": {},
    "idempotency_key": "string",
    "resource_uid": "string",
    "resource_name": "string",
    "resource_url": "string",
    "test": true,
    "generated": true,
    "chain_depth": 0,
    "ip": "string",
    "user_agent": "string",
    "browser": "string",
    "os": "string",
    "device_type": "string",
    "referrer": "string",
    "utm_source": "string",
    "utm_medium": "string",
    "utm_term": "string",
    "utm_content": "string",
    "utm_campaign": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Track a contact event

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

Requires an idempotency key via the Idempotency-Key header or idempotency_key body param. Duplicate events (same account + event type + idempotency key) return the existing event.

Body

application/json
eventstringrequired

Event type name (lowercase, underscores)

contact_idinteger
contact_emailstring<email>

Alternative to contact_id — resolves contact by email

idempotency_keystring

Idempotency key (alternative to header)

amountnumber<double>
resource_uidstring
resource_namestring
resource_urlstring<uri>
testbooleanfalse
dataobject

Custom event payload (max 32KB)

utm_sourcestring
utm_mediumstring
utm_termstring
utm_contentstring
utm_campaignstring

Parameters

Idempotency-Keystringheader

Idempotency key (alternative to body param)

Response

200OKobject

Duplicate event (idempotent — returns existing)

201Createdobject

Event created

400Bad Requestobject

Bad request

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Track a contact event
curl -X POST 'https://api.nitrosend.com/v1/my/events' \
  -H 'Content-Type: application/json' \
  -d '{
    "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: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "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 data = await response.json();
import requests

payload = {
  "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', json=payload)
data = response.json()
Request 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"
}
{
  "id": 0,
  "account_id": 0,
  "contact_id": 0,
  "user_id": 0,
  "event": "string",
  "amount": 0,
  "data": {},
  "idempotency_key": "string",
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "string",
  "test": true,
  "generated": true,
  "chain_depth": 0,
  "ip": "string",
  "user_agent": "string",
  "browser": "string",
  "os": "string",
  "device_type": "string",
  "referrer": "string",
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "id": 0,
  "account_id": 0,
  "contact_id": 0,
  "user_id": 0,
  "event": "string",
  "amount": 0,
  "data": {},
  "idempotency_key": "string",
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "string",
  "test": true,
  "generated": true,
  "chain_depth": 0,
  "ip": "string",
  "user_agent": "string",
  "browser": "string",
  "os": "string",
  "device_type": "string",
  "referrer": "string",
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Get an event

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

Parameters

idintegerrequiredpath

Response

200OKobject

Event

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get an event
curl -X GET 'https://api.nitrosend.com/v1/my/events/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/events/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/events/{id}')
data = response.json()
{
  "id": 0,
  "account_id": 0,
  "contact_id": 0,
  "user_id": 0,
  "event": "string",
  "amount": 0,
  "data": {},
  "idempotency_key": "string",
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "string",
  "test": true,
  "generated": true,
  "chain_depth": 0,
  "ip": "string",
  "user_agent": "string",
  "browser": "string",
  "os": "string",
  "device_type": "string",
  "referrer": "string",
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete an event

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

Parameters

idintegerrequiredpath

Response

200OKobject

Deleted event

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete an event
curl -X DELETE 'https://api.nitrosend.com/v1/my/events/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/events/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/events/{id}')
data = response.json()
200
{
  "id": 0,
  "account_id": 0,
  "contact_id": 0,
  "user_id": 0,
  "event": "string",
  "amount": 0,
  "data": {},
  "idempotency_key": "string",
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "string",
  "test": true,
  "generated": true,
  "chain_depth": 0,
  "ip": "string",
  "user_agent": "string",
  "browser": "string",
  "os": "string",
  "device_type": "string",
  "referrer": "string",
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Domains

Sending domain verification

List sending domains (paginated)

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

Parameters

pageinteger1query
perinteger30query

Response

200OKArray<object>

Paginated domains

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List sending domains (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/domains'
const response = await fetch('https://api.nitrosend.com/v1/my/domains', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/domains')
data = response.json()
200
[
  {
    "id": 0,
    "brand_id": 0,
    "name": "string",
    "provider": "ses",
    "integration_id": 0,
    "status": "pending",
    "dns_records": [
      {
        "record_type": "string",
        "name": "string",
        "value": "string",
        "priority": "string",
        "valid": "string"
      }
    ],
    "dns_health": {},
    "dns_setup_status": "unchecked",
    "verified_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z"
  }
]

Add a sending domain

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

Initiates domain verification. Returns DNS records that must be added at your domain registrar before calling POST /verify.

Body

application/json
domainobjectrequired
Show child attributes
namestringrequired

e.g. send.example.com

Response

201Createdobject

Domain registered with DNS records to configure

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Add a sending domain
curl -X POST 'https://api.nitrosend.com/v1/my/domains' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": {
      "name": "string"
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/domains', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "domain": {
        "name": "string"
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "domain": {
    "name": "string"
  }
}

response = requests.post('https://api.nitrosend.com/v1/my/domains', json=payload)
data = response.json()
Request Body
{
  "domain": {
    "name": "string"
  }
}
{
  "id": 0,
  "brand_id": 0,
  "name": "string",
  "provider": "ses",
  "integration_id": 0,
  "status": "pending",
  "dns_records": [
    {
      "record_type": "string",
      "name": "string",
      "value": "string",
      "priority": "string",
      "valid": "string"
    }
  ],
  "dns_health": {},
  "dns_setup_status": "unchecked",
  "verified_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a domain with DNS records and status

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

Parameters

idintegerrequiredpath

Response

200OKobject

Domain

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a domain with DNS records and status
curl -X GET 'https://api.nitrosend.com/v1/my/domains/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/domains/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/domains/{id}')
data = response.json()
{
  "id": 0,
  "brand_id": 0,
  "name": "string",
  "provider": "ses",
  "integration_id": 0,
  "status": "pending",
  "dns_records": [
    {
      "record_type": "string",
      "name": "string",
      "value": "string",
      "priority": "string",
      "valid": "string"
    }
  ],
  "dns_health": {},
  "dns_setup_status": "unchecked",
  "verified_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Remove a sending domain

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

Parameters

idintegerrequiredpath

Response

204No Content

Domain deleted

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Remove a sending domain
curl -X DELETE 'https://api.nitrosend.com/v1/my/domains/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/domains/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/domains/{id}')
data = response.json()

Verify domain DNS records

POST
https://api.nitrosend.com/v1/my/domains/{id}/verify

Checks if the required DNS records have propagated. If verified, completes the domain_verified onboarding step and enables sending.

Parameters

idintegerrequiredpath

Response

200OKobject

Domain verification status

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Verify domain DNS records
curl -X POST 'https://api.nitrosend.com/v1/my/domains/{id}/verify'
const response = await fetch('https://api.nitrosend.com/v1/my/domains/{id}/verify', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/domains/{id}/verify')
data = response.json()
200
{
  "id": 0,
  "brand_id": 0,
  "name": "string",
  "provider": "ses",
  "integration_id": 0,
  "status": "pending",
  "dns_records": [
    {
      "record_type": "string",
      "name": "string",
      "value": "string",
      "priority": "string",
      "valid": "string"
    }
  ],
  "dns_health": {},
  "dns_setup_status": "unchecked",
  "verified_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

Create an Entri bootstrap session for a pending domain

POST
https://api.nitrosend.com/v1/my/domains/{id}/entri_session

Returns a short-lived Entri JWT plus the DNS record payload needed to launch the Entri modal for a pending domain owned by the current brand.

Parameters

idintegerrequiredpath

Response

200OKobject

Entri bootstrap payload

404Not Foundobject

Resource not found

422Unprocessable Entityobject & object

Validation failed

429Too Many Requestsobject

Rate limit exceeded

503Service Unavailableobject

Upstream service unavailable

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create an Entri bootstrap session for a pending domain
curl -X POST 'https://api.nitrosend.com/v1/my/domains/{id}/entri_session'
const response = await fetch('https://api.nitrosend.com/v1/my/domains/{id}/entri_session', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/domains/{id}/entri_session')
data = response.json()
{
  "domain": {
    "id": 0,
    "name": "string",
    "status": "pending"
  },
  "entri": {
    "application_id": "string",
    "token": "string",
    "prefilled_domain": "string",
    "user_id": "string",
    "dns_records": [
      {
        "type": "string",
        "host": "string",
        "value": "string",
        "ttl": 0,
        "priority": 0
      }
    ]
  }
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Integrations

BYO provider integration management

List integrations (paginated)

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

Parameters

categorystringemailsmscrmquery
pageinteger1query
perinteger30query

Response

200OKArray<object>

Paginated integrations

400Bad Requestobject

Bad request

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List integrations (paginated)
curl -X GET 'https://api.nitrosend.com/v1/my/integrations'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/integrations')
data = response.json()
[
  {
    "id": 0,
    "provider": "mailgun",
    "category": "email",
    "active": true,
    "primary": true,
    "status": "pending",
    "connected_at": "2024-01-15T09:30:00Z",
    "last_tested_at": "2024-01-15T09:30:00Z",
    "error_message": "string",
    "config_summary": {},
    "secret_hints": {},
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Create or connect an email provider integration

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

Body

application/json
integrationobject | object | object | object | objectrequired

Response

201Createdobject

Integration created

400Bad Requestobject

Bad request

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create or connect an email provider integration
curl -X POST 'https://api.nitrosend.com/v1/my/integrations' \
  -H 'Content-Type: application/json' \
  -d '{
    "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: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "integration": {
        "provider": "mailgun",
        "api_key": "string",
        "domain": "string",
        "region": "string",
        "active": true
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": True
  }
}

response = requests.post('https://api.nitrosend.com/v1/my/integrations', json=payload)
data = response.json()
Request Body
{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}
{
  "id": 0,
  "provider": "mailgun",
  "category": "email",
  "active": true,
  "primary": true,
  "status": "pending",
  "connected_at": "2024-01-15T09:30:00Z",
  "last_tested_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "config_summary": {},
  "secret_hints": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get an integration

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

Parameters

idintegerrequiredpath

Response

200OKobject

Integration

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get an integration
curl -X GET 'https://api.nitrosend.com/v1/my/integrations/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/{id}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/integrations/{id}')
data = response.json()
{
  "id": 0,
  "provider": "mailgun",
  "category": "email",
  "active": true,
  "primary": true,
  "status": "pending",
  "connected_at": "2024-01-15T09:30:00Z",
  "last_tested_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "config_summary": {},
  "secret_hints": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Disconnect and delete an integration

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

Parameters

idintegerrequiredpath
confirmbooleanrequiredquery

Must be true to confirm the destructive action.

Response

204No Content

Integration deleted

400Bad Requestobject

Bad request

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Disconnect and delete an integration
curl -X DELETE 'https://api.nitrosend.com/v1/my/integrations/{id}'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/{id}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/integrations/{id}')
data = response.json()
400
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Update an email provider integration

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

Updates credentials or operational fields for an existing email provider. The provider cannot be changed once the integration exists.

Body

application/json
integrationobject | object | object | object | objectrequired

Parameters

idintegerrequiredpath

Response

200OKobject

Integration updated

400Bad Requestobject

Bad request

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update an email provider integration
curl -X PATCH 'https://api.nitrosend.com/v1/my/integrations/{id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration": {
      "provider": "mailgun",
      "api_key": "string",
      "domain": "string",
      "region": "string",
      "active": true
    }
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/{id}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "integration": {
        "provider": "mailgun",
        "api_key": "string",
        "domain": "string",
        "region": "string",
        "active": true
      }
    }),
});

const data = await response.json();
import requests

payload = {
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": True
  }
}

response = requests.patch('https://api.nitrosend.com/v1/my/integrations/{id}', json=payload)
data = response.json()
Request Body
{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}
{
  "id": 0,
  "provider": "mailgun",
  "category": "email",
  "active": true,
  "primary": true,
  "status": "pending",
  "connected_at": "2024-01-15T09:30:00Z",
  "last_tested_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "config_summary": {},
  "secret_hints": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Test integration connectivity

POST
https://api.nitrosend.com/v1/my/integrations/{id}/test

Parameters

idintegerrequiredpath

Response

200OKobject

Tested integration

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Test integration connectivity
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/{id}/test'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/{id}/test', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/integrations/{id}/test')
data = response.json()
{
  "id": 0,
  "provider": "mailgun",
  "category": "email",
  "active": true,
  "primary": true,
  "status": "pending",
  "connected_at": "2024-01-15T09:30:00Z",
  "last_tested_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "config_summary": {},
  "secret_hints": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Set an integration as the primary provider for its category

PATCH
https://api.nitrosend.com/v1/my/integrations/{id}/primary

Parameters

idintegerrequiredpath

Response

200OKobject

Integration marked primary

400Bad Requestobject

Bad request

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Set an integration as the primary provider for its category
curl -X PATCH 'https://api.nitrosend.com/v1/my/integrations/{id}/primary'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/{id}/primary', {
  method: 'PATCH',
});

const data = await response.json();
import requests

response = requests.patch('https://api.nitrosend.com/v1/my/integrations/{id}/primary')
data = response.json()
{
  "id": 0,
  "provider": "mailgun",
  "category": "email",
  "active": true,
  "primary": true,
  "status": "pending",
  "connected_at": "2024-01-15T09:30:00Z",
  "last_tested_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "config_summary": {},
  "secret_hints": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Start Attio OAuth connect flow

POST
https://api.nitrosend.com/v1/my/integrations/attio/connect

Returns an Attio OAuth authorize URL for the authenticated account/brand. The response URL includes a signed state payload and the API callback URI.

Response

200OKobject

OAuth authorize URL

401Unauthorizedobject

Not authenticated

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Start Attio OAuth connect flow
curl -X POST 'https://api.nitrosend.com/v1/my/integrations/attio/connect'
const response = await fetch('https://api.nitrosend.com/v1/my/integrations/attio/connect', {
  method: 'POST',
});

const data = await response.json();
import requests

response = requests.post('https://api.nitrosend.com/v1/my/integrations/attio/connect')
data = response.json()
{
  "authorize_url": "https://example.com"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Attio OAuth callback endpoint

GET
https://api.nitrosend.com/integrations/attio/callback

Public callback endpoint used by Attio after user authorization. Verifies signed state, exchanges auth code, and finalizes Attio integration connection.

Parameters

codestringquery
statestringquery
errorstringquery
error_descriptionstringquery

Response

200OKstring

OAuth callback processed (HTML)

400Bad Requeststring

Invalid callback request

422Unprocessable Entitystring

OAuth exchange or webhook provisioning failure

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Attio OAuth callback endpoint
curl -X GET 'https://api.nitrosend.com/integrations/attio/callback'
const response = await fetch('https://api.nitrosend.com/integrations/attio/callback', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/integrations/attio/callback')
data = response.json()
"string"
"string"
"string"

Brands

Brand identity, theme, and per-brand configuration

List brands

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

Response

200OKArray<object>

All brands for the account

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

List brands
curl -X GET 'https://api.nitrosend.com/v1/my/brands'
const response = await fetch('https://api.nitrosend.com/v1/my/brands', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/brands')
data = response.json()
200
[
  {
    "id": 0,
    "sid": "string",
    "account_id": 0,
    "brand_color": "string",
    "text_color": "string",
    "bg_color": "string",
    "font_heading": "string",
    "font_body": "string",
    "style_notes": "string",
    "tone": "string",
    "company_description": "string",
    "industry": "string",
    "example_copy": [
      "string"
    ],
    "default_header": {},
    "default_footer": {},
    "default_theme": {},
    "physical_address": "string",
    "company_name": "string",
    "source_url": "string",
    "last_scraped_at": "2024-01-15T09:30:00Z",
    "links": [
      {
        "url": "string",
        "icon": "string",
        "title": "string"
      }
    ],
    "logo": "string",
    "complete": true,
    "email_from_name": "string",
    "email_from_email": "string",
    "email_reply_to": "string",
    "test_email_recipients": [
      "user@example.com"
    ],
    "onboarding_state": {},
    "onboarding": {
      "steps": {},
      "progress": {
        "completed": 0,
        "total": 0
      }
    },
    "domain_verified": true,
    "can_send": true,
    "subscribed_contacts_count": 0,
    "using_sandbox": true,
    "sandbox_email": "string",
    "sandbox_monthly_cap": 0,
    "sandbox_sends_remaining": 0,
    "capabilities": {},
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
]

Create a brand

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

Body

application/json
brand_colorstring
text_colorstring
bg_colorstring
font_headingstring
font_bodystring
style_notesstring
tonestring
company_descriptionstring
industrystring
physical_addressstring
company_namestring
logostring

Signed blob ID or URL

email_from_namestring
email_from_emailstring<email>
email_reply_tostring<email>
test_email_recipientsArray<string>
example_copyArray<string>
linksArray<object>
Show child attributes
urlstring<uri>
iconstring
titlestring
default_headerobject
default_footerobject
default_themeobject

Response

201Createdobject

Brand created

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Create a brand
curl -X POST 'https://api.nitrosend.com/v1/my/brands' \
  -H 'Content-Type: application/json' \
  -d '{
    "brand_color": "string",
    "text_color": "string",
    "bg_color": "string",
    "font_heading": "string",
    "font_body": "string",
    "style_notes": "string",
    "tone": "string",
    "company_description": "string",
    "industry": "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",
    "test_email_recipients": [
      "user@example.com"
    ],
    "example_copy": [
      "string"
    ],
    "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: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "brand_color": "string",
      "text_color": "string",
      "bg_color": "string",
      "font_heading": "string",
      "font_body": "string",
      "style_notes": "string",
      "tone": "string",
      "company_description": "string",
      "industry": "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",
      "test_email_recipients": [
        "user@example.com"
      ],
      "example_copy": [
        "string"
      ],
      "links": [
        {
          "url": "https://example.com",
          "icon": "string",
          "title": "string"
        }
      ],
      "default_header": {},
      "default_footer": {},
      "default_theme": {}
    }),
});

const data = await response.json();
import requests

payload = {
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "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",
  "test_email_recipients": [
    "user@example.com"
  ],
  "example_copy": [
    "string"
  ],
  "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', json=payload)
data = response.json()
Request Body
{
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "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",
  "test_email_recipients": [
    "user@example.com"
  ],
  "example_copy": [
    "string"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}
{
  "id": 0,
  "sid": "string",
  "account_id": 0,
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "string",
  "example_copy": [
    "string"
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {},
  "physical_address": "string",
  "company_name": "string",
  "source_url": "string",
  "last_scraped_at": "2024-01-15T09:30:00Z",
  "links": [
    {
      "url": "string",
      "icon": "string",
      "title": "string"
    }
  ],
  "logo": "string",
  "complete": true,
  "email_from_name": "string",
  "email_from_email": "string",
  "email_reply_to": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "onboarding_state": {},
  "onboarding": {
    "steps": {},
    "progress": {
      "completed": 0,
      "total": 0
    }
  },
  "domain_verified": true,
  "can_send": true,
  "subscribed_contacts_count": 0,
  "using_sandbox": true,
  "sandbox_email": "string",
  "sandbox_monthly_cap": 0,
  "sandbox_sends_remaining": 0,
  "capabilities": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get a brand

GET
https://api.nitrosend.com/v1/my/brands/{sid}

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Brand

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get a brand
curl -X GET 'https://api.nitrosend.com/v1/my/brands/{sid}'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/brands/{sid}')
data = response.json()
{
  "id": 0,
  "sid": "string",
  "account_id": 0,
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "string",
  "example_copy": [
    "string"
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {},
  "physical_address": "string",
  "company_name": "string",
  "source_url": "string",
  "last_scraped_at": "2024-01-15T09:30:00Z",
  "links": [
    {
      "url": "string",
      "icon": "string",
      "title": "string"
    }
  ],
  "logo": "string",
  "complete": true,
  "email_from_name": "string",
  "email_from_email": "string",
  "email_reply_to": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "onboarding_state": {},
  "onboarding": {
    "steps": {},
    "progress": {
      "completed": 0,
      "total": 0
    }
  },
  "domain_verified": true,
  "can_send": true,
  "subscribed_contacts_count": 0,
  "using_sandbox": true,
  "sandbox_email": "string",
  "sandbox_monthly_cap": 0,
  "sandbox_sends_remaining": 0,
  "capabilities": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Delete a brand

DELETE
https://api.nitrosend.com/v1/my/brands/{sid}

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Deleted brand

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Delete a brand
curl -X DELETE 'https://api.nitrosend.com/v1/my/brands/{sid}'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}', {
  method: 'DELETE',
});

const data = await response.json();
import requests

response = requests.delete('https://api.nitrosend.com/v1/my/brands/{sid}')
data = response.json()
200
{
  "id": 0,
  "sid": "string",
  "account_id": 0,
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "string",
  "example_copy": [
    "string"
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {},
  "physical_address": "string",
  "company_name": "string",
  "source_url": "string",
  "last_scraped_at": "2024-01-15T09:30:00Z",
  "links": [
    {
      "url": "string",
      "icon": "string",
      "title": "string"
    }
  ],
  "logo": "string",
  "complete": true,
  "email_from_name": "string",
  "email_from_email": "string",
  "email_reply_to": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "onboarding_state": {},
  "onboarding": {
    "steps": {},
    "progress": {
      "completed": 0,
      "total": 0
    }
  },
  "domain_verified": true,
  "can_send": true,
  "subscribed_contacts_count": 0,
  "using_sandbox": true,
  "sandbox_email": "string",
  "sandbox_monthly_cap": 0,
  "sandbox_sends_remaining": 0,
  "capabilities": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Update a brand

PATCH
https://api.nitrosend.com/v1/my/brands/{sid}

Body

application/json
brand_colorstring
text_colorstring
bg_colorstring
font_headingstring
font_bodystring
style_notesstring
tonestring
company_descriptionstring
industrystring
physical_addressstring
company_namestring
logostring

Signed blob ID or URL

email_from_namestring
email_from_emailstring<email>
email_reply_tostring<email>
test_email_recipientsArray<string>
example_copyArray<string>
linksArray<object>
Show child attributes
urlstring<uri>
iconstring
titlestring
default_headerobject
default_footerobject
default_themeobject

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Updated brand

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update a brand
curl -X PATCH 'https://api.nitrosend.com/v1/my/brands/{sid}' \
  -H 'Content-Type: application/json' \
  -d '{
    "brand_color": "string",
    "text_color": "string",
    "bg_color": "string",
    "font_heading": "string",
    "font_body": "string",
    "style_notes": "string",
    "tone": "string",
    "company_description": "string",
    "industry": "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",
    "test_email_recipients": [
      "user@example.com"
    ],
    "example_copy": [
      "string"
    ],
    "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/{sid}', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "brand_color": "string",
      "text_color": "string",
      "bg_color": "string",
      "font_heading": "string",
      "font_body": "string",
      "style_notes": "string",
      "tone": "string",
      "company_description": "string",
      "industry": "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",
      "test_email_recipients": [
        "user@example.com"
      ],
      "example_copy": [
        "string"
      ],
      "links": [
        {
          "url": "https://example.com",
          "icon": "string",
          "title": "string"
        }
      ],
      "default_header": {},
      "default_footer": {},
      "default_theme": {}
    }),
});

const data = await response.json();
import requests

payload = {
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "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",
  "test_email_recipients": [
    "user@example.com"
  ],
  "example_copy": [
    "string"
  ],
  "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/{sid}', json=payload)
data = response.json()
Request Body
{
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "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",
  "test_email_recipients": [
    "user@example.com"
  ],
  "example_copy": [
    "string"
  ],
  "links": [
    {
      "url": "https://example.com",
      "icon": "string",
      "title": "string"
    }
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {}
}
{
  "id": 0,
  "sid": "string",
  "account_id": 0,
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "string",
  "example_copy": [
    "string"
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {},
  "physical_address": "string",
  "company_name": "string",
  "source_url": "string",
  "last_scraped_at": "2024-01-15T09:30:00Z",
  "links": [
    {
      "url": "string",
      "icon": "string",
      "title": "string"
    }
  ],
  "logo": "string",
  "complete": true,
  "email_from_name": "string",
  "email_from_email": "string",
  "email_reply_to": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "onboarding_state": {},
  "onboarding": {
    "steps": {},
    "progress": {
      "completed": 0,
      "total": 0
    }
  },
  "domain_verified": true,
  "can_send": true,
  "subscribed_contacts_count": 0,
  "using_sandbox": true,
  "sandbox_email": "string",
  "sandbox_monthly_cap": 0,
  "sandbox_sends_remaining": 0,
  "capabilities": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Auto-detect brand from website

POST
https://api.nitrosend.com/v1/my/brands/{sid}/scrape

Enqueues a background job that scrapes the URL for brand colors, fonts, logo, and tone. Returns 202 immediately. Poll GET /v1/my/brands/{sid} for results.

Body

application/json
urlstring<uri>required

Parameters

sidstringrequiredpath

Brand secure identifier

Response

202Acceptedobject

Scrape job enqueued

422Unprocessable Entityobject

Invalid URL

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Auto-detect brand from website
curl -X POST 'https://api.nitrosend.com/v1/my/brands/{sid}/scrape' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}/scrape', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "url": "https://example.com"
    }),
});

const data = await response.json();
import requests

payload = {
  "url": "https://example.com"
}

response = requests.post('https://api.nitrosend.com/v1/my/brands/{sid}/scrape', json=payload)
data = response.json()
Request Body
{
  "url": "https://example.com"
}
{
  "status": "scraping",
  "url": "https://example.com"
}
{
  "error": "string"
}

Get brand onboarding state

GET
https://api.nitrosend.com/v1/my/brands/{sid}/onboarding

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Onboarding state for the brand

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get brand onboarding state
curl -X GET 'https://api.nitrosend.com/v1/my/brands/{sid}/onboarding'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}/onboarding', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/brands/{sid}/onboarding')
data = response.json()
{
  "steps": {},
  "progress": {
    "completed": 0,
    "total": 0
  }
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Complete a brand onboarding step

POST
https://api.nitrosend.com/v1/my/brands/{sid}/onboarding/steps

Body

application/json
stepstringbrand_setupdomain_verifiedfirst_contactfirst_sendrequired

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Updated onboarding state

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Complete a brand onboarding step
curl -X POST 'https://api.nitrosend.com/v1/my/brands/{sid}/onboarding/steps' \
  -H 'Content-Type: application/json' \
  -d '{
    "step": "brand_setup"
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}/onboarding/steps', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "step": "brand_setup"
    }),
});

const data = await response.json();
import requests

payload = {
  "step": "brand_setup"
}

response = requests.post('https://api.nitrosend.com/v1/my/brands/{sid}/onboarding/steps', json=payload)
data = response.json()
Request Body
{
  "step": "brand_setup"
}
{
  "steps": {},
  "progress": {
    "completed": 0,
    "total": 0
  }
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Get brand setup center state

GET
https://api.nitrosend.com/v1/my/brands/{sid}/setup_center

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Setup center state for the brand

404Not Foundobject

Resource not found

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Get brand setup center state
curl -X GET 'https://api.nitrosend.com/v1/my/brands/{sid}/setup_center'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}/setup_center', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/my/brands/{sid}/setup_center')
data = response.json()
{
  "cards": [
    {
      "id": "brand_scan",
      "complete": true,
      "acknowledged": true,
      "acknowledged_at": "2024-01-15T09:30:00Z"
    }
  ],
  "sections": {
    "required": [
      "string"
    ],
    "recommended": [
      "string"
    ]
  },
  "progress": {
    "completed": 0,
    "total": 0
  },
  "seen": true,
  "dismissed": true,
  "complete": true
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Update brand setup center state

PATCH
https://api.nitrosend.com/v1/my/brands/{sid}/setup_center

Body

application/json

Provide one of seen, dismissed, or card.

seenboolean
dismissedboolean
cardstringbrand_scandnsplanconnect_agentimport_subscribersconnect_transactional
metadataobject

Parameters

sidstringrequiredpath

Brand secure identifier

Response

200OKobject

Updated setup center state

422Unprocessable Entityobject & object

Validation failed

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Update brand setup center state
curl -X PATCH 'https://api.nitrosend.com/v1/my/brands/{sid}/setup_center' \
  -H 'Content-Type: application/json' \
  -d '{
    "seen": true,
    "dismissed": true,
    "card": "brand_scan",
    "metadata": {}
  }'
const response = await fetch('https://api.nitrosend.com/v1/my/brands/{sid}/setup_center', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "seen": true,
      "dismissed": true,
      "card": "brand_scan",
      "metadata": {}
    }),
});

const data = await response.json();
import requests

payload = {
  "seen": True,
  "dismissed": True,
  "card": "brand_scan",
  "metadata": {}
}

response = requests.patch('https://api.nitrosend.com/v1/my/brands/{sid}/setup_center', json=payload)
data = response.json()
Request Body
{
  "seen": true,
  "dismissed": true,
  "card": "brand_scan",
  "metadata": {}
}
{
  "cards": [
    {
      "id": "brand_scan",
      "complete": true,
      "acknowledged": true,
      "acknowledged_at": "2024-01-15T09:30:00Z"
    }
  ],
  "sections": {
    "required": [
      "string"
    ],
    "recommended": [
      "string"
    ]
  },
  "progress": {
    "completed": 0,
    "total": 0
  },
  "seen": true,
  "dismissed": true,
  "complete": true
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}

Public

Unauthenticated public endpoints

Add or attach a public signup contact

POST
https://api.nitrosend.com/v1/public/contacts

Idempotent public signup endpoint for landing pages and embeds. Authenticate with a brand public API key in the Bearer token.

Body

application/json
emailstring<email>required
list_idintegerrequired
sourcestring | null

Response

201Createdobject

Contact accepted

401Unauthorizedobject

Not authenticated

404Not Foundobject

Resource not found

422Unprocessable Entityobject & object

Validation failed

429Too Many Requestsobject

Rate limit exceeded

Authorization

BearerAuthhttp (bearer)

API key (nskey_live_...) or JWT token. API key is checked first; if not found, falls back to Devise JWT authentication.

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

Add or attach a public signup contact
curl -X POST 'https://api.nitrosend.com/v1/public/contacts' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "list_id": 0,
    "source": "string"
  }'
const response = await fetch('https://api.nitrosend.com/v1/public/contacts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "email": "user@example.com",
      "list_id": 0,
      "source": "string"
    }),
});

const data = await response.json();
import requests

payload = {
  "email": "user@example.com",
  "list_id": 0,
  "source": "string"
}

response = requests.post('https://api.nitrosend.com/v1/public/contacts', json=payload)
data = response.json()
Request Body
{
  "email": "user@example.com",
  "list_id": 0,
  "source": "string"
}
{
  "ok": true
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string",
  "validation_errors": {}
}
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

Get available plans

GET
https://api.nitrosend.com/v1/app

Response

200OKobject

Active plans

Get available plans
curl -X GET 'https://api.nitrosend.com/v1/app'
const response = await fetch('https://api.nitrosend.com/v1/app', {
  method: 'GET',
});

const data = await response.json();
import requests

response = requests.get('https://api.nitrosend.com/v1/app')
data = response.json()
200
{
  "plans": [
    {
      "id": 0,
      "name": "string",
      "active": true
    }
  ]
}

Models

Error

object
codeintegerrequired
messagestringrequired
errorbooleanrequired
error_codestring | null

Optional machine-readable error reason.

Example
{
  "code": 0,
  "message": "string",
  "error": true,
  "error_code": "string"
}

User

object
idinteger
first_namestring | null
last_namestring | null
emailstring<email>
mobilestring | null
country_codestring | null
adminboolean
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "mobile": "string",
  "country_code": "string",
  "admin": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Account

object
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

account_tierstringfreepaidtrusted
safe_mode_enabledboolean
billingobject
Show child attributes
plan_namestring
wallet_balance_centsinteger
auto_topupboolean
resourcesobject
Show child attributes
emailobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
smsobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
aiobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger
brandsArray<object>
Show child attributes
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
font_headingstring | null
font_bodystring | null
style_notesstring | null
tonestring | null
company_descriptionstring | null
industrystring | null
example_copyArray<string> | null
default_headerobject | null
default_footerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
linksArray<object> | null
Show child attributes
urlstring
iconstring
titlestring
logostring | null

Logo URL

completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
test_email_recipientsArray<string>
onboarding_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
subscribed_contacts_countinteger

Count of subscribed contacts in this brand.

using_sandboxboolean
sandbox_emailstring | null
sandbox_monthly_capinteger
sandbox_sends_remaininginteger
capabilitiesobject
created_atstring<date-time>
updated_atstring<date-time>
teamobject
Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "name": "string",
  "avatar": "string",
  "banner": "string",
  "account_tier": "free",
  "safe_mode_enabled": true,
  "billing": {
    "plan_name": "string",
    "wallet_balance_cents": 0,
    "auto_topup": true,
    "resources": {
      "email": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      },
      "sms": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      },
      "ai": {
        "used": 0,
        "allowance": 0,
        "remaining": 0,
        "overage_rate": 0
      }
    },
    "lifetime": {
      "email_sent": 0,
      "sms_sent": 0,
      "ai_used": 0
    }
  },
  "brands": [
    {
      "id": 0,
      "sid": "string",
      "account_id": 0,
      "brand_color": "string",
      "text_color": "string",
      "bg_color": "string",
      "font_heading": "string",
      "font_body": "string",
      "style_notes": "string",
      "tone": "string",
      "company_description": "string",
      "industry": "string",
      "example_copy": [
        "string"
      ],
      "default_header": {},
      "default_footer": {},
      "default_theme": {},
      "physical_address": "string",
      "company_name": "string",
      "source_url": "string",
      "last_scraped_at": "2024-01-15T09:30:00Z",
      "links": [
        {
          "url": "string",
          "icon": "string",
          "title": "string"
        }
      ],
      "logo": "string",
      "complete": true,
      "email_from_name": "string",
      "email_from_email": "string",
      "email_reply_to": "string",
      "test_email_recipients": [
        "user@example.com"
      ],
      "onboarding_state": {},
      "onboarding": {
        "steps": {},
        "progress": {
          "completed": 0,
          "total": 0
        }
      },
      "domain_verified": true,
      "can_send": true,
      "subscribed_contacts_count": 0,
      "using_sandbox": true,
      "sandbox_email": "string",
      "sandbox_monthly_cap": 0,
      "sandbox_sends_remaining": 0,
      "capabilities": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "team": {
    "seat_limit": 0,
    "seat_count": 0,
    "member_count": 0,
    "invite_count": 0,
    "current_role": "string",
    "can_manage_team": true
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

AccountTeam

object
accountobject
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

account_tierstringfreepaidtrusted
safe_mode_enabledboolean
billingobject
Show child attributes
plan_namestring
wallet_balance_centsinteger
auto_topupboolean
resourcesobject
Show child attributes
emailobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
smsobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
aiobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger
brandsArray<object>
Show child attributes
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
font_headingstring | null
font_bodystring | null
style_notesstring | null
tonestring | null
company_descriptionstring | null
industrystring | null
example_copyArray<string> | null
default_headerobject | null
default_footerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
linksArray<object> | null
Show child attributes
urlstring
iconstring
titlestring
logostring | null

Logo URL

completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
test_email_recipientsArray<string>
onboarding_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
subscribed_contacts_countinteger

Count of subscribed contacts in this brand.

using_sandboxboolean
sandbox_emailstring | null
sandbox_monthly_capinteger
sandbox_sends_remaininginteger
capabilitiesobject
created_atstring<date-time>
updated_atstring<date-time>
teamobject
Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>
membershipsArray<object>
Show child attributes
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>
invitesArray<object>
Show child attributes
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
accessible_accountsArray<object>
Show child attributes
idinteger
namestring | null
avatarstring | null

Signed blob ID

bannerstring | null

Signed blob ID

account_tierstringfreepaidtrusted
safe_mode_enabledboolean
billingobject
Show child attributes
plan_namestring
wallet_balance_centsinteger
auto_topupboolean
resourcesobject
Show child attributes
emailobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
smsobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
aiobject
Show child attributes
usedinteger
allowanceinteger
remaininginteger
overage_ratenumber
lifetimeobject
Show child attributes
email_sentinteger
sms_sentinteger
ai_usedinteger
brandsArray<object>
Show child attributes
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
font_headingstring | null
font_bodystring | null
style_notesstring | null
tonestring | null
company_descriptionstring | null
industrystring | null
example_copyArray<string> | null
default_headerobject | null
default_footerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
linksArray<object> | null
Show child attributes
urlstring
iconstring
titlestring
logostring | null

Logo URL

completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
test_email_recipientsArray<string>
onboarding_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
subscribed_contacts_countinteger

Count of subscribed contacts in this brand.

using_sandboxboolean
sandbox_emailstring | null
sandbox_monthly_capinteger
sandbox_sends_remaininginteger
capabilitiesobject
created_atstring<date-time>
updated_atstring<date-time>
teamobject
Show child attributes
seat_limitinteger
seat_countinteger
member_countinteger
invite_countinteger
current_rolestring | null
can_manage_teamboolean
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "account": {
    "id": 0,
    "name": "string",
    "avatar": "string",
    "banner": "string",
    "account_tier": "free",
    "safe_mode_enabled": true,
    "billing": {
      "plan_name": "string",
      "wallet_balance_cents": 0,
      "auto_topup": true,
      "resources": {
        "email": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        },
        "sms": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        },
        "ai": {
          "used": 0,
          "allowance": 0,
          "remaining": 0,
          "overage_rate": 0
        }
      },
      "lifetime": {
        "email_sent": 0,
        "sms_sent": 0,
        "ai_used": 0
      }
    },
    "brands": [
      {
        "id": 0,
        "sid": "string",
        "account_id": 0,
        "brand_color": "string",
        "text_color": "string",
        "bg_color": "string",
        "font_heading": "string",
        "font_body": "string",
        "style_notes": "string",
        "tone": "string",
        "company_description": "string",
        "industry": "string",
        "example_copy": [
          "string"
        ],
        "default_header": {},
        "default_footer": {},
        "default_theme": {},
        "physical_address": "string",
        "company_name": "string",
        "source_url": "string",
        "last_scraped_at": "2024-01-15T09:30:00Z",
        "links": [
          {
            "url": "string",
            "icon": "string",
            "title": "string"
          }
        ],
        "logo": "string",
        "complete": true,
        "email_from_name": "string",
        "email_from_email": "string",
        "email_reply_to": "string",
        "test_email_recipients": [
          "user@example.com"
        ],
        "onboarding_state": {},
        "onboarding": {
          "steps": {},
          "progress": {
            "completed": 0,
            "total": 0
          }
        },
        "domain_verified": true,
        "can_send": true,
        "subscribed_contacts_count": 0,
        "using_sandbox": true,
        "sandbox_email": "string",
        "sandbox_monthly_cap": 0,
        "sandbox_sends_remaining": 0,
        "capabilities": {},
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    ],
    "team": {
      "seat_limit": 0,
      "seat_count": 0,
      "member_count": 0,
      "invite_count": 0,
      "current_role": "string",
      "can_manage_team": true
    },
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "memberships": [
    {
      "id": 0,
      "role": "member",
      "user_id": 0,
      "email": "user@example.com",
      "name": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "invites": [
    {
      "id": 0,
      "account_id": 0,
      "email": "user@example.com",
      "role": "member",
      "token": "string",
      "status": "pending",
      "accepted_at": "2024-01-15T09:30:00Z",
      "revoked_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "accessible_accounts": [
    {
      "id": 0,
      "name": "string",
      "avatar": "string",
      "banner": "string",
      "account_tier": "free",
      "safe_mode_enabled": true,
      "billing": {
        "plan_name": "string",
        "wallet_balance_cents": 0,
        "auto_topup": true,
        "resources": {
          "email": {
            "used": 0,
            "allowance": 0,
            "remaining": 0,
            "overage_rate": 0
          },
          "sms": {
            "used": 0,
            "allowance": 0,
            "remaining": 0,
            "overage_rate": 0
          },
          "ai": {
            "used": 0,
            "allowance": 0,
            "remaining": 0,
            "overage_rate": 0
          }
        },
        "lifetime": {
          "email_sent": 0,
          "sms_sent": 0,
          "ai_used": 0
        }
      },
      "brands": [
        {
          "id": 0,
          "sid": "string",
          "account_id": 0,
          "brand_color": "string",
          "text_color": "string",
          "bg_color": "string",
          "font_heading": "string",
          "font_body": "string",
          "style_notes": "string",
          "tone": "string",
          "company_description": "string",
          "industry": "string",
          "example_copy": [
            "string"
          ],
          "default_header": {},
          "default_footer": {},
          "default_theme": {},
          "physical_address": "string",
          "company_name": "string",
          "source_url": "string",
          "last_scraped_at": "2024-01-15T09:30:00Z",
          "links": [
            {
              "url": "string",
              "icon": "string",
              "title": "string"
            }
          ],
          "logo": "string",
          "complete": true,
          "email_from_name": "string",
          "email_from_email": "string",
          "email_reply_to": "string",
          "test_email_recipients": [
            "user@example.com"
          ],
          "onboarding_state": {},
          "onboarding": {
            "steps": {},
            "progress": {
              "completed": 0,
              "total": 0
            }
          },
          "domain_verified": true,
          "can_send": true,
          "subscribed_contacts_count": 0,
          "using_sandbox": true,
          "sandbox_email": "string",
          "sandbox_monthly_cap": 0,
          "sandbox_sends_remaining": 0,
          "capabilities": {},
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z"
        }
      ],
      "team": {
        "seat_limit": 0,
        "seat_count": 0,
        "member_count": 0,
        "invite_count": 0,
        "current_role": "string",
        "can_manage_team": true
      },
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

AccountMembership

object
idinteger
rolestringmemberadminowner
user_idinteger
emailstring<email>
namestring | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "role": "member",
  "user_id": 0,
  "email": "user@example.com",
  "name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

AccountInvite

object
idinteger
account_idinteger
emailstring<email>
rolestringmemberadmin
tokenstring
statusstringpendingacceptedrevokedexpired
accepted_atstring<date-time> | null
revoked_atstring<date-time> | null
expires_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "account_id": 0,
  "email": "user@example.com",
  "role": "member",
  "token": "string",
  "status": "pending",
  "accepted_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

OAuthPopupAccount

object
idintegerrequired
namestringrequired
can_manageboolean
needs_subscribebooleanrequired
Example
{
  "id": 0,
  "name": "string",
  "can_manage": true,
  "needs_subscribe": true
}

OAuthPopupPlan

object
idintegerrequired
namestringrequired
slugstringrequired
base_price_centsintegerrequired
intervalstring | null
Example
{
  "id": 0,
  "name": "string",
  "slug": "string",
  "base_price_cents": 0,
  "interval": "string"
}

OAuthPopupContext

object
accountsArray<object>required
Show child attributes
idintegerrequired
namestringrequired
can_manageboolean
needs_subscribebooleanrequired
plansArray<object>required
Show child attributes
idintegerrequired
namestringrequired
slugstringrequired
base_price_centsintegerrequired
intervalstring | null
stripe_publishable_keystring | null
Example
{
  "accounts": [
    {
      "id": 0,
      "name": "string",
      "can_manage": true,
      "needs_subscribe": true
    }
  ],
  "plans": [
    {
      "id": 0,
      "name": "string",
      "slug": "string",
      "base_price_cents": 0,
      "interval": "string"
    }
  ],
  "stripe_publishable_key": "string"
}

OAuthPopupSubscribeRequest

object
plan_idintegerrequired
account_idinteger | null
stripe_tokenstring | null
Example
{
  "plan_id": 0,
  "account_id": 0,
  "stripe_token": "string"
}

OAuthPopupSubscribeResponse

object
next_stepstringconsentrequired
Example
{
  "next_step": "consent"
}

OAuthLaunchRequest

object
providerstringgoogle_oauth2githubrequired
auth_intentstringappagentapp
auth_stepstringloginsignuplogin
resume_urlstring<uri> | null

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

Example
{
  "provider": "google_oauth2",
  "auth_intent": "app",
  "auth_step": "login",
  "resume_url": "https://example.com"
}

OAuthLaunchResponse

object
launch_urlstring<uri>required
Example
{
  "launch_url": "https://example.com"
}

Brand

object
idinteger
sidstringread only

Public secure identifier (non-sequential)

account_idinteger
brand_colorstring | null
text_colorstring | null
bg_colorstring | null
font_headingstring | null
font_bodystring | null
style_notesstring | null
tonestring | null
company_descriptionstring | null
industrystring | null
example_copyArray<string> | null
default_headerobject | null
default_footerobject | null
default_themeobject | null
physical_addressstring | null
company_namestring | null
source_urlstring | null
last_scraped_atstring<date-time> | null
linksArray<object> | null
Show child attributes
urlstring
iconstring
titlestring
logostring | null

Logo URL

completeboolean

True when brand_color and company_name are set

email_from_namestring | null
email_from_emailstring | null
email_reply_tostring | null
test_email_recipientsArray<string>
onboarding_stateobject

JSONB — keys are step names, values are completion metadata

onboardingobject
Show child attributes
stepsobject

Current state of each onboarding step

progressobject
Show child attributes
completedinteger
totalinteger
domain_verifiedboolean
can_sendboolean
subscribed_contacts_countinteger

Count of subscribed contacts in this brand.

using_sandboxboolean
sandbox_emailstring | null
sandbox_monthly_capinteger
sandbox_sends_remaininginteger
capabilitiesobject
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "sid": "string",
  "account_id": 0,
  "brand_color": "string",
  "text_color": "string",
  "bg_color": "string",
  "font_heading": "string",
  "font_body": "string",
  "style_notes": "string",
  "tone": "string",
  "company_description": "string",
  "industry": "string",
  "example_copy": [
    "string"
  ],
  "default_header": {},
  "default_footer": {},
  "default_theme": {},
  "physical_address": "string",
  "company_name": "string",
  "source_url": "string",
  "last_scraped_at": "2024-01-15T09:30:00Z",
  "links": [
    {
      "url": "string",
      "icon": "string",
      "title": "string"
    }
  ],
  "logo": "string",
  "complete": true,
  "email_from_name": "string",
  "email_from_email": "string",
  "email_reply_to": "string",
  "test_email_recipients": [
    "user@example.com"
  ],
  "onboarding_state": {},
  "onboarding": {
    "steps": {},
    "progress": {
      "completed": 0,
      "total": 0
    }
  },
  "domain_verified": true,
  "can_send": true,
  "subscribed_contacts_count": 0,
  "using_sandbox": true,
  "sandbox_email": "string",
  "sandbox_monthly_cap": 0,
  "sandbox_sends_remaining": 0,
  "capabilities": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

SetupCenterPayload

object
cardsArray<object>
Show child attributes
idstringbrand_scandnsplanconnect_agentimport_subscribersconnect_transactional
completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
sectionsobject
Show child attributes
requiredArray<string>
recommendedArray<string>
progressobject
Show child attributes
completedinteger
totalinteger
seenboolean
dismissedboolean
completeboolean
Example
{
  "cards": [
    {
      "id": "brand_scan",
      "complete": true,
      "acknowledged": true,
      "acknowledged_at": "2024-01-15T09:30:00Z"
    }
  ],
  "sections": {
    "required": [
      "string"
    ],
    "recommended": [
      "string"
    ]
  },
  "progress": {
    "completed": 0,
    "total": 0
  },
  "seen": true,
  "dismissed": true,
  "complete": true
}

SetupCenterCard

object
idstringbrand_scandnsplanconnect_agentimport_subscribersconnect_transactional
completeboolean
acknowledgedboolean
acknowledged_atstring<date-time> | null
Example
{
  "id": "brand_scan",
  "complete": true,
  "acknowledged": true,
  "acknowledged_at": "2024-01-15T09:30:00Z"
}

Contact

object
idinteger
brand_idinteger | null
uuidstring<uuid>
first_namestring | null
last_namestring | null
sourcestring | null
country_codestring | null
dataobject

Custom key-value data. The reserved key tags holds an array of string labels used for segmentation and targeting.

subscribed_phoneboolean
subscribed_emailboolean
verification_statusstringverifiedsuppressedunverified
enrichment_statusstringenrichednot_enriched
list_idsArray<integer>
last_interacted_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
channelsArray<object>
Show child attributes
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "brand_id": 0,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "string",
  "last_name": "string",
  "source": "string",
  "country_code": "string",
  "data": {
    "tags": [
      "vip",
      "newsletter"
    ],
    "plan": "pro"
  },
  "subscribed_phone": true,
  "subscribed_email": true,
  "verification_status": "verified",
  "enrichment_status": "enriched",
  "list_ids": [
    0
  ],
  "last_interacted_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "channels": [
    {
      "id": 0,
      "contact_id": 0,
      "kind": "email",
      "value": "string",
      "subscribed": true,
      "verified": true,
      "opt_in_at": "2024-01-15T09:30:00Z",
      "opt_out_at": "2024-01-15T09:30:00Z",
      "sent_count": 0,
      "fail_count": 0,
      "data": {},
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

ContactChannel

object
idinteger
contact_idinteger
kindstringemailphone
valuestring
subscribedboolean
verifiedboolean
opt_in_atstring<date-time> | null
opt_out_atstring<date-time> | null
sent_countinteger
fail_countinteger
dataobject
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "contact_id": 0,
  "kind": "email",
  "value": "string",
  "subscribed": true,
  "verified": true,
  "opt_in_at": "2024-01-15T09:30:00Z",
  "opt_out_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "fail_count": 0,
  "data": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

ContactList

object
idinteger
account_idinteger
brand_idinteger | null
namestring
contacts_countinteger
segment_idinteger | null
staleboolean
last_populated_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "contacts_count": 0,
  "segment_id": 0,
  "stale": true,
  "last_populated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

ListDeleteWarning

object
campaign_namesArray<string>
flow_namesArray<string>
Example
{
  "campaign_names": [
    "string"
  ],
  "flow_names": [
    "string"
  ]
}

BulkListContactsRequest

object
actionstringaddremoverequired

Add existing contacts to the list or remove them from it.

emailsArray<string>required
Example
{
  "action": "add",
  "emails": [
    "user@example.com"
  ]
}

BulkListContactsResponse

object
actionstringaddremove
list_idinteger
addedinteger

Contacts newly added for add actions

removedinteger

Contacts removed for remove actions

already_in_listArray<string>
not_in_listArray<string>
not_foundArray<string>
invalid_emailsArray<string>
Example
{
  "action": "add",
  "list_id": 0,
  "added": 0,
  "removed": 0,
  "already_in_list": [
    "user@example.com"
  ],
  "not_in_list": [
    "user@example.com"
  ],
  "not_found": [
    "user@example.com"
  ],
  "invalid_emails": [
    "string"
  ]
}

Import

object
idinteger
resourcestringcontacts
parserstringdefault
statusstringpendingprocessingfailedcanceledcomplete
total_rowsinteger | null
success_rowsinteger | null
failed_rowsinteger | null
import_errorsArray<Array<integer | string>>

Row-level errors as [line_number, message, source].

columnsobject | null
optionsobject | null
started_atstring<date-time> | null
ended_atstring<date-time> | null
created_atstring<date-time>
Example
{
  "id": 0,
  "resource": "contacts",
  "parser": "default",
  "status": "pending",
  "total_rows": 0,
  "success_rows": 0,
  "failed_rows": 0,
  "import_errors": [
    [
      0
    ]
  ],
  "columns": {},
  "options": {},
  "started_at": "2024-01-15T09:30:00Z",
  "ended_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

Segment

object
idinteger
account_idinteger
brand_idinteger | null
namestring
filtersArray<object>
Show child attributes
namestringrequired

Filter name from flows.yml: 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

predicatestringrequired

Ransack predicate: eq, not_eq, cont, not_cont, start, end, gt, lt, gteq, lteq, present, blank, true, false, in, not_in

valueanyrequired

Filter value — string, number, boolean, or array for in/not_in

created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "name": "string",
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

SegmentFilters

array
Array<object>
Show child attributes
namestringrequired

Filter name from flows.yml: 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

predicatestringrequired

Ransack predicate: eq, not_eq, cont, not_cont, start, end, gt, lt, gteq, lteq, present, blank, true, false, in, not_in

valueanyrequired

Filter value — string, number, boolean, or array for in/not_in

Example
[
  {
    "name": "string",
    "predicate": "string"
  }
]

Campaign

object
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedcompleted
approval_statestring
channelstringemailsms
namestring
dataobject
scheduled_atstring<date-time> | null
sent_countinteger
editablebooleanread only

True when the campaign's content/audience/template can be edited. False for live, paused, completed, cancelled, archived, and for scheduled campaigns within 5 minutes of their scheduled_at. When false, PUT update accepts only name-only payloads and status transitions (Resume / Cancel); anything else returns 422 campaign_locked. Use POST /duplicate to fork into a new draft.

created_atstring<date-time>
updated_atstring<date-time>
triggerobject
Show child attributes
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — use contact_list_ids

contact_list_idsArray<integer>

Contact list IDs targeted by this trigger

dataobject | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
templateobject | null
templatesArray<object>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
subjectstring | null
bodystring | null
preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designobject | null
variablesobject
generation_idinteger | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "channel": "email",
  "name": "string",
  "data": {},
  "scheduled_at": "2024-01-15T09:30:00Z",
  "sent_count": 0,
  "editable": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "trigger": {
    "id": 0,
    "flow_id": 0,
    "event": "string",
    "audience_type": "lists",
    "segment_id": 0,
    "contact_list_id": 0,
    "contact_list_ids": [
      0
    ],
    "data": {},
    "triggered_count": 0,
    "last_triggered_at": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "template": {
    "id": 0,
    "name": "string",
    "flow_id": 0,
    "action_id": 0,
    "subject": "string",
    "body": "string",
    "preheader": "string",
    "from_name": "string",
    "from_email": "string",
    "reply_to": "string",
    "design": {
      "sections": [
        {
          "type": "header",
          "props": {},
          "styles": {
            "background_color": "string",
            "padding": "string",
            "align": "left"
          }
        }
      ],
      "theme": {
        "brand_color": "string",
        "bg_color": "string",
        "text_color": "string",
        "font_body": "string",
        "font_heading": "string",
        "logo_url": "string"
      }
    },
    "variables": {},
    "generation_id": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

Message

object
idinteger
channelstringemailsms
tostring
subjectstring | null
statusstringqueuedsentfailed
provider_idstring | null
flow_idinteger | null

Source flow ID (null for transactional)

source_typestring | nullcampaignflow

campaign, flow, or null (transactional)

source_namestring | null

Name of source campaign or flow

sent_atstring<date-time> | null
created_atstring<date-time>
Example
{
  "id": 0,
  "channel": "email",
  "to": "string",
  "subject": "string",
  "status": "queued",
  "provider_id": "string",
  "flow_id": 0,
  "source_type": "campaign",
  "source_name": "string",
  "sent_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

Template

object
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
subjectstring | null
bodystring | null
preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designobject | null
variablesobject
generation_idinteger | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "name": "string",
  "flow_id": 0,
  "action_id": 0,
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "string",
  "reply_to": "string",
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  },
  "variables": {},
  "generation_id": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

EmailStarter

object
idstring
categorystring
namestring
descriptionstring
iconstring
suggested_goalsArray<string>
designobject

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring
preview_htmlstring | null
Example
{
  "id": "string",
  "category": "string",
  "name": "string",
  "description": "string",
  "icon": "string",
  "suggested_goals": [
    "string"
  ],
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  },
  "preview_html": "string"
}

TemplateSummary

object
idinteger
namestring | null
subjectstring | null
preheaderstring | null
flow_idinteger | null
section_countinteger
section_typesArray<string>
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "name": "string",
  "subject": "string",
  "preheader": "string",
  "flow_id": 0,
  "section_count": 0,
  "section_types": [
    "string"
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Flow

object
idinteger
account_idinteger
brand_idinteger | null
statusstringdraftactivepausedarchived
approval_statestring
namestring
goalstring | null
triggerobject

Trigger as returned by Flow::Format.dump

Show child attributes
eventstring
segment_idinteger | null
contact_list_idinteger | null
dataobject | null
stepsArray<any>
sent_countinteger
created_atstring<date-time>
updated_atstring<date-time>
templatesArray<object>
Show child attributes
idinteger
namestring | null
flow_idinteger | null
action_idinteger | null
subjectstring | null
bodystring | null
preheaderstring | null
from_namestring | null
from_emailstring | null
reply_tostring | null
designobject | null
variablesobject
generation_idinteger | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "account_id": 0,
  "brand_id": 0,
  "status": "draft",
  "approval_state": "string",
  "name": "string",
  "goal": "string",
  "trigger": {
    "event": "string",
    "segment_id": 0,
    "contact_list_id": 0,
    "data": {}
  },
  "steps": [],
  "sent_count": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "templates": [
    {
      "id": 0,
      "name": "string",
      "flow_id": 0,
      "action_id": 0,
      "subject": "string",
      "body": "string",
      "preheader": "string",
      "from_name": "string",
      "from_email": "string",
      "reply_to": "string",
      "design": {
        "sections": [
          {
            "type": "header",
            "props": {},
            "styles": {
              "background_color": "string",
              "padding": "string",
              "align": "left"
            }
          }
        ],
        "theme": {
          "brand_color": "string",
          "bg_color": "string",
          "text_color": "string",
          "font_body": "string",
          "font_heading": "string",
          "logo_url": "string"
        }
      },
      "variables": {},
      "generation_id": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ]
}

FlowTrigger

object
idinteger
flow_idinteger
eventstring
audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — use contact_list_ids

contact_list_idsArray<integer>

Contact list IDs targeted by this trigger

dataobject | null
triggered_countinteger
last_triggered_atstring<date-time> | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "flow_id": 0,
  "event": "string",
  "audience_type": "lists",
  "segment_id": 0,
  "contact_list_id": 0,
  "contact_list_ids": [
    0
  ],
  "data": {},
  "triggered_count": 0,
  "last_triggered_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

FlowTriggerInput

object
eventstring

Built-in: contact_add, keyword, message, list_add, list_remove, product_view, checkout, cart_add, cart_remove, cart_abandoned, browse_abandoned. Custom: any lowercase alphanumeric with underscores.

audience_typestring | nulllistssegmentall_contacts

Explicit campaign audience target; null means no audience selected.

segment_idinteger | null
contact_list_idinteger | nulldeprecated

Deprecated — use contact_list_ids

contact_list_idsArray<integer>

Contact list IDs to target

dataobject
Example
{
  "event": "string",
  "audience_type": "lists",
  "segment_id": 0,
  "contact_list_id": 0,
  "contact_list_ids": [
    0
  ],
  "data": {}
}

FlowTriggerOutput

object

Trigger as returned by Flow::Format.dump

eventstring
segment_idinteger | null
contact_list_idinteger | null
dataobject | null
Example
{
  "event": "string",
  "segment_id": 0,
  "contact_list_id": 0,
  "data": {}
}

FlowStepInput

object
typestringemailsmswaitsplitemit_eventrequired
subjectstring

Email step: subject line

bodystring

SMS body or email plain text

preheaderstring

Email step: preheader

from_namestring
from_emailstring
reply_tostring
designobject

Email template design document

Show child attributes
sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring
durationinteger

Wait step: seconds

filtersArray<object>

Split step: condition filters

Show child attributes
namestring
predicatestring
valueany
yesArray<any>

Split step: yes branch

noArray<any>

Split step: no branch

event_namestring

Emit event step: event to fire

forward_event_databooleanfalse
event_dataobject
transactionalbooleanfalse
Example
{
  "type": "email",
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "from_name": "string",
  "from_email": "string",
  "reply_to": "string",
  "design": {
    "sections": [
      {
        "type": "header",
        "props": {},
        "styles": {
          "background_color": "string",
          "padding": "string",
          "align": "left"
        }
      }
    ],
    "theme": {
      "brand_color": "string",
      "bg_color": "string",
      "text_color": "string",
      "font_body": "string",
      "font_heading": "string",
      "logo_url": "string"
    }
  },
  "duration": 0,
  "filters": [
    {
      "name": "string",
      "predicate": "string"
    }
  ],
  "yes": [],
  "no": [],
  "event_name": "string",
  "forward_event_data": false,
  "event_data": {},
  "transactional": false
}

FlowStepOutput

object

Step as returned by Flow::Format.dump

typestringemailsmswaitsplitemit_event
subjectstring
bodystring
preheaderstring
durationinteger
filtersArray<object>
yesArray<any>
noArray<any>
event_namestring
forward_event_databoolean
Example
{
  "type": "email",
  "subject": "string",
  "body": "string",
  "preheader": "string",
  "duration": 0,
  "filters": [
    {}
  ],
  "yes": [],
  "no": [],
  "event_name": "string",
  "forward_event_data": true
}

Event

object
idinteger
account_idinteger
contact_idinteger
user_idinteger
eventstring
amountnumber<double> | null
dataobject
idempotency_keystring | null
resource_uidstring | null
resource_namestring | null
resource_urlstring | null
testboolean
generatedboolean
chain_depthinteger
ipstring | null
user_agentstring | null
browserstring | null
osstring | null
device_typestring | null
referrerstring | null
utm_sourcestring | null
utm_mediumstring | null
utm_termstring | null
utm_contentstring | null
utm_campaignstring | null
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "account_id": 0,
  "contact_id": 0,
  "user_id": 0,
  "event": "string",
  "amount": 0,
  "data": {},
  "idempotency_key": "string",
  "resource_uid": "string",
  "resource_name": "string",
  "resource_url": "string",
  "test": true,
  "generated": true,
  "chain_depth": 0,
  "ip": "string",
  "user_agent": "string",
  "browser": "string",
  "os": "string",
  "device_type": "string",
  "referrer": "string",
  "utm_source": "string",
  "utm_medium": "string",
  "utm_term": "string",
  "utm_content": "string",
  "utm_campaign": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Domain

object
idinteger
brand_idinteger | null
namestring
providerstringses
integration_idinteger | null
statusstringpendingverifiedfailed
dns_recordsArray<object> | null
Show child attributes
record_typestring
namestring
valuestring
prioritystring | null
validstring
dns_healthobject | null
dns_setup_statusstringuncheckedincompletereadyverified
verified_atstring<date-time> | null
created_atstring<date-time>
Example
{
  "id": 0,
  "brand_id": 0,
  "name": "string",
  "provider": "ses",
  "integration_id": 0,
  "status": "pending",
  "dns_records": [
    {
      "record_type": "string",
      "name": "string",
      "value": "string",
      "priority": "string",
      "valid": "string"
    }
  ],
  "dns_health": {},
  "dns_setup_status": "unchecked",
  "verified_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

EntriSessionResponse

object
domainobject
Show child attributes
idinteger
namestring
statusstringpendingverifiedfailed
entriobject
Show child attributes
application_idstring
tokenstring
prefilled_domainstring
user_idstring
dns_recordsArray<object>
Show child attributes
typestring
hoststring
valuestring
ttlinteger
priorityinteger | null
Example
{
  "domain": {
    "id": 0,
    "name": "string",
    "status": "pending"
  },
  "entri": {
    "application_id": "string",
    "token": "string",
    "prefilled_domain": "string",
    "user_id": "string",
    "dns_records": [
      {
        "type": "string",
        "host": "string",
        "value": "string",
        "ttl": 0,
        "priority": 0
      }
    ]
  }
}

EntriDnsRecord

object
typestring
hoststring
valuestring
ttlinteger
priorityinteger | null
Example
{
  "type": "string",
  "host": "string",
  "value": "string",
  "ttl": 0,
  "priority": 0
}

Integration

object
idinteger
providerstringmailgunsespostmarkresendsendgridtwilioattio
categorystringemailsmscrm
activeboolean
primaryboolean
statusstringpendingconnectederror
connected_atstring<date-time> | null
last_tested_atstring<date-time> | null
error_messagestring | null
config_summaryobject
secret_hintsobject
created_atstring<date-time>
updated_atstring<date-time>
Example
{
  "id": 0,
  "provider": "mailgun",
  "category": "email",
  "active": true,
  "primary": true,
  "status": "pending",
  "connected_at": "2024-01-15T09:30:00Z",
  "last_tested_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "config_summary": {},
  "secret_hints": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

IntegrationWriteRequest

object
integrationobject | object | object | object | objectrequired
Example
{
  "integration": {
    "provider": "mailgun",
    "api_key": "string",
    "domain": "string",
    "region": "string",
    "active": true
  }
}

MailgunIntegrationInput

object
providerstringmailgunrequired
api_keystringrequired
domainstringrequired

Mailgun sending domain

regionstring | null

Optional Mailgun region hint

activebooleantrue
Example
{
  "provider": "mailgun",
  "api_key": "string",
  "domain": "string",
  "region": "string",
  "active": true
}

SesIntegrationInput

object
providerstringsesrequired
access_key_idstringrequired
secret_access_keystringrequired
regionstringrequired

AWS SES region

activebooleantrue
Example
{
  "provider": "ses",
  "access_key_id": "string",
  "secret_access_key": "string",
  "region": "string",
  "active": true
}

PostmarkIntegrationInput

object
providerstringpostmarkrequired
server_tokenstringrequired

Postmark server token for sending email

account_tokenstringrequired

Postmark account token for domains API access

activebooleantrue
Example
{
  "provider": "postmark",
  "server_token": "string",
  "account_token": "string",
  "active": true
}

ResendIntegrationInput

object
providerstringresendrequired
api_keystringrequired
activebooleantrue
Example
{
  "provider": "resend",
  "api_key": "string",
  "active": true
}

SendgridIntegrationInput

object
providerstringsendgridrequired
api_keystringrequired
activebooleantrue
Example
{
  "provider": "sendgrid",
  "api_key": "string",
  "active": true
}

Plan

object
idinteger
namestring
activeboolean
Example
{
  "id": 0,
  "name": "string",
  "active": true
}

EmailDesign

object

Email template design document

sectionsArray<object>
Show child attributes
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
themeobject

Theme overrides merged on top of brand theme

Show child attributes
brand_colorstring
bg_colorstring
text_colorstring
font_bodystring
font_headingstring
logo_urlstring
Example
{
  "sections": [
    {
      "type": "header",
      "props": {},
      "styles": {
        "background_color": "string",
        "padding": "string",
        "align": "left"
      }
    }
  ],
  "theme": {
    "brand_color": "string",
    "bg_color": "string",
    "text_color": "string",
    "font_body": "string",
    "font_heading": "string",
    "logo_url": "string"
  }
}

EmailSection

object
typestringheaderherotextimagebuttoncolumnsproductsocialdividerspacerfooterrequired
propsobject

Section-specific properties (see email component spec)

stylesobject
Show child attributes
background_colorstring
paddingstring
alignstringleftcenterright
Example
{
  "type": "header",
  "props": {},
  "styles": {
    "background_color": "string",
    "padding": "string",
    "align": "left"
  }
}

EmailComponentSpec

object

Full schema for email design sections. Each component has type, description, props (with types, required flags, defaults), and tips.

versioninteger
design_guidelinesstring
componentsArray<object>
Show child attributes
typestring
descriptionstring
tipsArray<string>
propsobject
common_stylesobject
variablesArray<string>
theme_fieldsArray<string>
Example
{
  "version": 0,
  "design_guidelines": "string",
  "components": [
    {
      "type": "string",
      "description": "string",
      "tips": [
        "string"
      ],
      "props": {}
    }
  ],
  "common_styles": {},
  "variables": [
    "string"
  ],
  "theme_fields": [
    "string"
  ]
}

FlowSpec

object

Schema for flow step types, trigger events, and segment filter names. 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.

filtersobject
triggersArray<object>
Show child attributes
titlestring
eventstring
stepsArray<object>
Show child attributes
typestring
titlestring
summarystring
paramsobject
Example
{
  "filters": {},
  "triggers": [
    {
      "title": "string",
      "event": "string"
    }
  ],
  "steps": [
    {
      "type": "string",
      "title": "string",
      "summary": "string",
      "params": {}
    }
  ]
}
Built withSourcey