Send your key in the Authorization header as a Bearer token on every request. Keys belong to one workspace, are stored hashed, show their last use and can be revoked at any time. Each key has only the scopes you tick:
messages:sendSend messages
messages:readRead message status
contacts:writeCreate and update contacts
events:writeSend events (automations)
otpOne-time codes (OTP)
Keep keys on your server. Never put a key in an app, a web page or a public repository – anyone with the key can send from your balance.
Messages
Send a message
POST/api/v1/messagesmessages:send
Queues one message on one channel and answers 202 with the message. The cost is taken from the balance when the message is queued and given back if it fails on every route. Send the same Idempotency-Key again and you get the first message back instead of a second one.
Field
What it is
channelrequiredemail · sms · whatsapp
The channel to send on.
torequiredstring
An email address, or a phone number in international format (+15035550142).
textstring
The text of an SMS, the plain-text part of an email, or a free WhatsApp reply inside the 24-hour window.
subject · htmlstring
Email only: the subject and the HTML body.
fromstring
A verified from-address or an approved SMS sender ID. Empty = the workspace default.
template · variablesstring · object
WhatsApp: the name of an approved template and the values of its placeholders.
fallbackarray
Channels to try next when this one fails, e.g. ["sms"].
Email with HTML
{
"channel": "email",
"to": "ana@example.com",
"subject": "Your receipt for order #4821",
"html": "<h1>Thank you!</h1><p>Your order is on its way.</p>",
"text": "Thank you! Your order is on its way."
}
Messages
Message status
GET/api/v1/messages/{id}messages:read
Returns the message with its current status. A status only moves forward:
queuedWaiting in the queue
sendingHanded to a provider
sentAccepted by the provider
deliveredDelivery confirmed by the provider
openedEmail opened
clickedA link was clicked
repliedThe contact answered
failedFailed on every route – credit given back
bouncedThe address does not accept mail
Some SMS providers do not report delivery. Their messages stay at "sent" – we never show "delivered" without a report.
Workspace
Balance
GET/api/v1/balanceany key
The prepaid credit of the key's workspace in USD – check it before a large batch.
Audience
Create or update a contact
POST/api/v1/contactscontacts:write
Finds the contact by email or phone and updates it, or creates it. Lists (by id, shown in Contacts › Lists) and tags (by name) are added; a list with double opt-in sends its confirmation first.
We create the code, send it and check it – you never store it. Codes have 6 digits, expire after 10 minutes and allow 5 attempts (the request can ask for other values). Add a fallback and the code goes out on the next channel when the first one fails.
Add an endpoint in Developers › Webhooks and pick its events. Every delivery is a POST with a JSON body and the header SendNest-Signature. A failed delivery is tried again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h; every attempt is in the delivery log.
message.sentMessage sent
message.deliveredMessage delivered
message.failedMessage failed
message.openedEmail opened
message.clickedLink clicked
message.bouncedEmail bounced
message.repliedReply received
contact.unsubscribedContact unsubscribed
otp.verifiedOTP verified
Check the signature
The header holds the time (t) and an HMAC-SHA256 (v1) of "t.raw body" made with the endpoint's secret. Compare in constant time and refuse old times.
PHP
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_SENDNEST_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $raw, $endpointSecret);
if (abs(time() - (int) $sig['t']) > 300 || ! hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(400); exit; // not from us
}
Errors & limits
When something goes wrong
Errors answer with an HTTP status and a JSON body with an error code and a message. The message is written for people – show it in your logs. {"error": {"code": "…", "message": "…"} }
Status
Meaning
401
The key is missing, wrong or revoked.
402
Not enough balance for this message – add credit.
403
The key lacks the scope, or the workspace is suspended.
404
No such message or code in this workspace.
422
A field is missing or not valid; the contact unsubscribed or is suppressed.
429
Too many requests: 120 per minute per workspace. Wait for the Retry-After header.
Install SendNestCampaigns, inbox and reports on your home screen.
We use a few cookies to keep you signed in and remember your theme.