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.
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
https://api.nitrosend.com/v1/myAll endpoints are prefixed with /v1/my and scoped to your account.
Authentication
Every request requires a Bearer token in the Authorization header:
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).
Quick examples
Send an email
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
curl https://api.nitrosend.com/v1/my/campaigns \
-H "Authorization: Bearer $NITROSEND_API_KEY"Create a contact
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
curl https://api.nitrosend.com/v1/my/account \
-H "Authorization: Bearer $NITROSEND_API_KEY"Language examples
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
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
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 resultTransactional 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:
{
"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.
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
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 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 owns the full MCP, CLI, and REST journey; Purchase lifecycle defines state and authority. Use the generated API reference for exact fields.
Explicit prepaid validation
Email validation is never included or triggered by import, schedule, or send. Quote exactly one current-Brand audience first:
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:
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
| 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 for detailed request/response schemas.
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:
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
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
Errors return JSON with a consistent structure:
{
"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
The full API specification is available as OpenAPI 3.1 YAML:
https://api.nitrosend.com/openapi.yamlImport this into any tool that supports OpenAPI — Postman, Insomnia, Swagger UI, or API clients in any language.
