# REST API {#rest-api}


The Nitrosend REST API works with any HTTP client. Use it to integrate email marketing into your app, connect to automation platforms like Zapier or n8n, or build custom tools in any programming language.



> [!IMPORTANT]
> All plans, including free plans, have full access to Nitrosend MCP/API/CLI. REST API access is not restricted to paid plans; plan limits apply to usage volume and paid add-ons.




## Base URL {#base-url}


```
https://api.nitrosend.com/v1/my
```

All endpoints are prefixed with `/v1/my` and scoped to your account.


## Authentication {#authentication}


Every request requires a Bearer token in the `Authorization` header:

```bash
Authorization: Bearer <your-nitrosend-api-key>
```

Get your API key from **Settings > API Keys** in the Nitrosend dashboard ([app.nitrosend.com/my/settings/api-keys](https://app.nitrosend.com/my/settings/api-keys)).


## Quick examples {#quick-examples}



### Send an email {#send-an-email}


```bash
curl -X POST https://api.nitrosend.com/v1/my/messages \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user-123" \
  -d '{
    "channel": "email",
    "to": "user@example.com",
    "subject": "Welcome to our platform",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    "body": "Welcome! Thanks for signing up."
  }'
```


### List campaigns {#list-campaigns}


```bash
curl https://api.nitrosend.com/v1/my/campaigns \
  -H "Authorization: Bearer $NITROSEND_API_KEY"
```


### Create a contact {#create-a-contact}


```bash
curl -X POST https://api.nitrosend.com/v1/my/contacts \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "opt_in": true
  }'
```

Leave `opt_in` out of ordinary contact updates to keep the contact's current subscription. A new email address keeps Nitrosend's default email subscription; SMS requires opt-in. Set `opt_in: true` only when recording consent, or `opt_in: false` to unsubscribe an existing contact's supplied address. An opt-in does not remove a delivery suppression.

In the TypeScript SDK, the same field is `optIn`.


### Get account status {#get-account-status}


```bash
curl https://api.nitrosend.com/v1/my/account \
  -H "Authorization: Bearer $NITROSEND_API_KEY"
```


## Language examples {#language-examples}



### Python {#python}


```python
import requests

API_KEY = "nskey_live_your_key_here"
BASE_URL = "https://api.nitrosend.com/v1/my"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Send an email
response = requests.post(f"{BASE_URL}/messages", headers=HEADERS, json={
    "channel": "email",
    "to": "user@example.com",
    "subject": "Hello from Python",
    "html": "<h1>Hi!</h1>",
    "body": "Hi!"
})
print(response.json())

# List campaigns
campaigns = requests.get(f"{BASE_URL}/campaigns", headers=HEADERS)
print(campaigns.json())
```


### JavaScript / Node.js {#javascript--nodejs}


```javascript
const API_KEY = "nskey_live_your_key_here";
const BASE_URL = "https://api.nitrosend.com/v1/my";
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// Send an email
const response = await fetch(`${BASE_URL}/messages`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "email",
    to: "user@example.com",
    subject: "Hello from Node.js",
    html: "<h1>Hi!</h1>",
    body: "Hi!",
  }),
});
console.log(await response.json());

// List campaigns
const campaigns = await fetch(`${BASE_URL}/campaigns`, { headers });
console.log(await campaigns.json());
```


### Ruby {#ruby}


```ruby
require "net/http"
require "json"

API_KEY = "nskey_live_your_key_here"
BASE_URL = "https://api.nitrosend.com/v1/my"

def nitrosend_request(method, path, body = nil)
  uri = URI("#{BASE_URL}#{path}")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = case method
            when :get then Net::HTTP::Get.new(uri)
            when :post then Net::HTTP::Post.new(uri)
            end

  request["Authorization"] = "Bearer #{API_KEY}"
  request["Content-Type"] = "application/json"
  request.body = body.to_json if body

  JSON.parse(http.request(request).body)
end

# Send an email
result = nitrosend_request(:post, "/messages", {
  channel: "email",
  to: "user@example.com",
  subject: "Hello from Ruby",
  html: "<h1>Hi!</h1>",
  body: "Hi!"
})
puts result
```


## Transactional messages {#transactional-messages}


`POST /v1/my/messages` queues a single transactional email or SMS and returns
the message resource. Delivery happens through Nitrosend's normal background
sender, so the response means "accepted for sending", not "delivered".

For email, pass `channel: "email"`, `to`, `subject`, and one of `html`,
`body`, or `template_id`. `body` is plain text; HTML belongs in `html`.
Optional per-message delivery options are available for email only:

```json
{
  "channel": "email",
  "from": "Acme <hello@example.com>",
  "to": "user@example.com",
  "subject": "Your receipt",
  "html": "<p>Thanks for your purchase.</p>",
  "body": "Thanks for your purchase.",
  "reply_to": "support@example.com",
  "headers": { "X-Entity-Ref-ID": "order_123" },
  "tags": { "kind": "receipt", "plan": "pro" }
}
```

`from` / `from_email` must resolve to a verified sender identity for the brand.
Reserved provider headers and reserved Nitrosend tag keys are rejected. System
tags such as `account_id`, `brand_id`, and `message_id` are always controlled by
Nitrosend.

For SES senders, custom tag names and values may contain only ASCII letters,
numbers, underscores and hyphens. Unsupported tags return `422` naming the tag
before a message is queued. Other providers retain their own tag rules.

`In-Reply-To` and `References` are accepted custom headers. Pass at most 20
headers, with names up to 80 characters (`A–Z`, `a–z`, digits and hyphens) and
values up to 2,000 characters without line breaks. The envelope headers
`From`, `To`, `Cc`, `Bcc`, `Subject`, `Reply-To`, `Return-Path`, `DKIM-Signature`,
`List-Unsubscribe`, `List-Unsubscribe-Post`, `Message-ID` and `MIME-Version`
are reserved, as are headers starting with `X-Nitro-` or `Content-`.

The agent tool `nitro_send_message` accepts the same `from`, `from_email`,
`from_name`, `reply_to`, `headers` and `tags` options for transactional email.
For Inbox conversations, use `nitro_inbox_action` with `compose` or
`send_reply`; it handles the inbox sender and thread headers for you.

After provider acceptance, `GET /v1/my/messages/{id}` returns the actual email
`rfc_message_id`. It is `null` until available; do not derive it from
`provider_id`. Agents can read it through `nitro_query` with
`entity: "messages", filters: { id: message_id }`, or by retrying the original
send with its unchanged payload and idempotency key. For a custom threaded
transactional message, enclose the returned ID in angle brackets (if needed) in `In-Reply-To`
and include it in `References`.

Every send requires an idempotency key, in the `Idempotency-Key` header or the
`idempotency_key` field; without one the request returns
`400 idempotency_key_required`. Give each message its own stable key and reuse
it only to retry that message: the same key with the same payload returns the
original message, and with a different payload returns `409 idempotency_conflict`.

Ordinary HTML author comments do not count as personalization placeholders.
Visible content, including Outlook conditional content, still needs valid,
resolvable placeholders.

Temporary provider refusals, such as throttling or paused sending, remain
queued for retry on the original message. Permanent refusals become failed.
An uncertain provider outcome is not automatically resent, because the
provider might already have accepted it. Keep the original idempotency key
when checking or retrying your request.

To learn what happened to a message after it is accepted (sent, delivered,
bounced, failed and more) without polling, register a
[webhook](https://docs.nitrosend.com/integrations/webhooks.md).


## Suppressions {#suppressions}


`GET /v1/my/suppressions` lists the account's active email suppressions by
default. Use it to inspect hard bounces, soft-bounce suppressions, complaints,
manual suppressions, and the bounded provider diagnostic text retained from the
source feedback event.

Common filters include `email`, `reason`, `source_provider`, and `active=false`
for expired suppressions.


## Delivery capacity {#delivery-capacity}


`GET /v1/my/delivery/status` returns the current Brand's read-only delivery
projection: the account's fixed plan/standing allowance, plus pacing and a
bounded public reason/remediation. This endpoint never
authorizes or reserves a send. The actual send still passes through the single
delivery authority, so clients must not calculate headroom from a plan name.


## Plan checkout and prepaid funding {#plan-checkout-and-prepaid-funding}


Plan purchase and prepaid balance are separate account-scoped lifecycles. Send
a stable `Idempotency-Key` when creating either purchase. For a plan, call
`POST /v1/my/subscription/checkout`, complete provider approval when requested,
then poll `GET /v1/my/subscription/checkout_status?purchase_id=...` until the
requested plan is active.

For prepaid balance, inspect `GET /v1/my/billing/funding` first. Create a
funding purchase with `POST /v1/my/billing/funding/purchases`, passing
`amount_cents`, `currency`, and a stable `Idempotency-Key`. Poll
`GET /v1/my/billing/funding/purchases/{id}` until the purchase is credited.

Checkout creation, browser redirect, and webhook delivery alone are not
completion proof. [Payments for agents](https://docs.nitrosend.com/guides/agent-payments.md) owns the full
MCP, CLI, and REST journey; [Purchase lifecycle](https://docs.nitrosend.com/concepts/payment-lifecycle.md)
defines state and authority. Use the generated [API reference](https://docs.nitrosend.com/api.md) for exact
fields.


## Explicit prepaid validation {#explicit-prepaid-validation}


Email validation is never included or triggered by import, schedule, or send.
Quote exactly one current-Brand audience first:

```bash
curl -X POST https://api.nitrosend.com/v1/my/validation_operations/quote \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_id": 42}'
```

After inspecting the candidate counts, funding state, and maximum prepaid
charge, start the durable operation with a stable idempotency key:

```bash
curl -X POST https://api.nitrosend.com/v1/my/validation_operations \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: validation-list-42-2026-08" \
  -d '{"list_id": 42}'
```

The request must contain exactly one of `contact_channel_ids`, `contact_ids`,
`list_id`, or `segment_id`. Reusing the key with the same audience returns or
resumes the same operation; changing the audience conflicts. Poll the operation
and list its retained per-candidate items. Validation does not prove consent;
qualifying current results contribute to the one standing rank that selects the
plan allowance.


## Endpoint reference {#endpoint-reference}


| Action | Method | Endpoint |
|--------|--------|----------|
| **Billing** | | |
| Create or reuse plan checkout | `POST` | `/subscription/checkout` |
| Reconcile plan checkout | `GET` | `/subscription/checkout_status` |
| Get prepaid funding status | `GET` | `/billing/funding` |
| Create or reuse funding purchase | `POST` | `/billing/funding/purchases` |
| Reconcile funding purchase | `GET` | `/billing/funding/purchases/{id}` |
| **Messages** | | |
| Send a message | `POST` | `/messages` |
| List messages | `GET` | `/messages` |
| **Webhooks** | | |
| List webhooks | `GET` | `/webhooks` |
| Create webhook | `POST` | `/webhooks` |
| Send test event | `POST` | `/webhooks/{id}/test` |
| List deliveries | `GET` | `/webhooks/{id}/deliveries` |
| **Suppressions** | | |
| List suppressions | `GET` | `/suppressions` |
| **Delivery** | | |
| Get capacity and pacing status | `GET` | `/delivery/status` |
| **Email validation** | | |
| Quote validation | `POST` | `/validation_operations/quote` |
| Start or resume validation | `POST` | `/validation_operations` |
| Get validation operation | `GET` | `/validation_operations/{id}` |
| List validation results | `GET` | `/validation_operations/{id}/items` |
| **Events** | | |
| Track a contact event | `POST` | `/events` |
| List events | `GET` | `/events` |
| **Campaigns** | | |
| List campaigns | `GET` | `/campaigns` |
| Create campaign | `POST` | `/campaigns` |
| Get campaign | `GET` | `/campaigns/{id}` |
| Update campaign | `PATCH` | `/campaigns/{id}` |
| Send campaign | `POST` | `/campaigns/{id}/send` |
| **Contacts** | | |
| List contacts | `GET` | `/contacts` |
| Create contact | `POST` | `/contacts` |
| Bulk import contacts | `POST` | `/imports` |
| Poll import status | `GET` | `/imports/{id}` |
| **Lists** | | |
| List contact lists | `GET` | `/lists` |
| Create list | `POST` | `/lists` |
| Add/remove contacts by email | `POST` | `/lists/{id}/contacts/bulk` |
| **Templates** | | |
| List templates | `GET` | `/templates` |
| Create template | `POST` | `/templates` |
| Get template | `GET` | `/templates/{id}` |
| Update template | `PATCH` | `/templates/{id}` |
| Send test email | `POST` | `/templates/{id}/send_test` |
| **Flows** | | |
| List flows | `GET` | `/flows` |
| Create flow | `POST` | `/flows` |
| **Segments** | | |
| List segments | `GET` | `/segments` |
| **Account** | | |
| Get account info | `GET` | `/account` |

See the full [API Reference](https://docs.nitrosend.com/api.md) for detailed request/response schemas.


## Bulk imports {#bulk-imports}


Use `POST /v1/my/imports` with `multipart/form-data` to upload a CSV. The
response includes an import `id`; poll `GET /v1/my/imports/{id}` for status,
row counts, and row-level errors. For contact imports, pass `options` with
`list_ids` so imported contacts are assigned to the target list:

```bash
curl -X POST https://api.nitrosend.com/v1/my/imports \
  -H "Authorization: Bearer $NITROSEND_API_KEY" \
  -F "file=@contacts.csv" \
  -F "resource=contacts" \
  -F 'options={"list_ids":[88]}'
```


## Pagination {#pagination}


List endpoints return paginated results. Pagination headers are included in the response:

| Header | Description |
|--------|-------------|
| `X-Total-Count` | Total number of records |
| `X-Total-Pages` | Total number of pages |
| `X-Page-Number` | Current page number |

Use `?page=2&limit=25` query parameters to navigate pages.


## Error handling {#error-handling}


Errors return JSON with a consistent structure:

```json
{
  "error": true,
  "code": "validation_error",
  "message": "Email is required",
  "validation_errors": {
    "email": ["can't be blank"]
  }
}
```

| Status code | Meaning |
|-------------|---------|
| `200` | Success |
| `201` | Created |
| `401` | Invalid or missing API key |
| `404` | Resource not found |
| `422` | Validation error |
| `429` | Rate limited |


## OpenAPI spec {#openapi-spec}


The full API specification is available as OpenAPI 3.1 YAML:

```
https://api.nitrosend.com/openapi.yaml
```

Import this into any tool that supports OpenAPI — Postman, Insomnia, Swagger UI, or API clients in any language.
