Send transactional email from your app.
Use one endpoint to send HTML, text, or template-wrapped email through Sendhiiv. Generate keys inside the dashboard; read the reference here without logging in.
POST https://api.sendhiiv.com/api/v1/messagesSend one or more emails by posting JSON to the messages endpoint. Use template_key for either a saved layout or a complete message template.
Prefer not to hand-roll HTTP? There are official SDKs for Node.js and .NET that handle auth, error codes, and retry rules for you.
Official SDKs
Both SDKs are thin wrappers over the messages endpoint: typed request and response objects, the error codes on this page surfaced as real exception types, and automatic retries for 429 rate limits only — the one failure that can never double-send. Install from the registry; full guides live in each package README.
npm install sendhiivconst { Sendhiiv } = require("sendhiiv");
const sendhiiv = new Sendhiiv(process.env.SENDHIIV_API_KEY);
await sendhiiv.messages.send({
// from is optional — omit it to send from the shared
// sender until your own domain is verified
from: "Acme <hello@yourdomain.com>",
to: "customer@example.com",
subject: "Welcome aboard",
html: "<p>Your account is ready.</p>",
});npm · GitHub — TypeScript definitions included; works with both require and import.
dotnet add package Sendhiivusing Sendhiiv;
var sendhiiv = new SendhiivClient(apiKey);
await sendhiiv.Messages.SendAsync(new SendMessageParams
{
// From is optional — omit it to send from the shared
// sender until your own domain is verified
From = "Acme <hello@yourdomain.com>",
To = { "customer@example.com" },
Subject = "Welcome aboard",
Html = "<p>Your account is ready.</p>",
});NuGet · GitHub — installs into classic ASP.NET MVC / Web API / WebForms apps too; TLS 1.2 is enabled automatically on old frameworks.
Authentication
Add your API key to every request in the Authorization header. Keep API keys on your server, never in browser code.
Authorization: Bearer YOUR_API_KEYIf your HTTP client asks for Basic Auth instead of a bearer token, enter api as the username and your API key as the password. Both formats authenticate the same key.
SMTP relay
Prefer SMTP, or using software that only speaks SMTP (WordPress, Laravel, CRMs)? Send through Sendhiiv's SMTP relay instead of the HTTP API. SMTP sends are tracked exactly like API sends — same delivery, open and click tracking.
Create an SMTP credential in your dashboard under API keys → SMTP relay, then point your mailer at:
Host: smtp.sendhiiv.com
Port: 587 (STARTTLS) or 465 (TLS)
Username: <your SMTP username>
Password: <your SMTP password>Use an address on your verified domain in the message From header, or omit it to use the shared sender.
Drip batches
For larger API recipient lists, set send_mode todrip. Sendhiiv creates queued log rows immediately, sends the first batch now, then schedules the remaining batches through the mail queue.
{
"to": ["first@example.com", "second@example.com", "third@example.com"],
"subject": "Product update",
"html": "<p>Here is what changed.</p>",
"send_mode": "drip",
"batch_size": 50,
"batch_interval_minutes": 15
}Activity Logs label these rows as api drip and show the scheduled batch time while the email is waiting to send.
Templates
Sendhiiv has two template types. Layouts wrap the HTML you pass in the request. Message templates are complete emails and can be sent with variables only.
{
"to": "customer@example.com",
"subject": "Welcome aboard",
"template_key": "brand-layout",
"html": "<p>Hi {{firstName}}, your account is ready.</p>",
"variables": {
"firstName": "Amina"
}
}{
"to": "customer@example.com",
"template_key": "welcome-offer",
"variables": {
"firstName": "Amina"
}
}For message templates, html is optional. If the saved template includes {{content}}, the HTML you pass is placed there. Otherwise Sendhiiv sends the saved message as-is.
Subject is simple: the subject you pass in the request is used first. The saved message-template subject is only a fallback.
Code examples
Replace you@yourdomain.com in from with an address on your verified domain. If you have not added a domain yet, omit from and Sendhiiv sends from the shared address.
curl -X POST https://api.sendhiiv.com/api/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Your App <you@yourdomain.com>",
"to": "customer@example.com",
"subject": "Welcome aboard",
"template_key": "brand-layout",
"html": "<p>Hi there, your account is ready.</p>"
}'const response = await fetch("https://api.sendhiiv.com/api/v1/messages", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "Your App <you@yourdomain.com>",
to: "customer@example.com",
subject: "Welcome aboard",
template_key: "brand-layout",
html: "<p>Hi there, your account is ready.</p>",
}),
});
console.log(await response.json());import axios from "axios";
const { data } = await axios.post(
"https://api.sendhiiv.com/api/v1/messages",
{
from: "Your App <you@yourdomain.com>",
to: "customer@example.com",
subject: "Welcome aboard",
template_key: "brand-layout",
html: "<p>Hi there, your account is ready.</p>",
},
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
}
);
console.log(data);import requests
response = requests.post(
"https://api.sendhiiv.com/api/v1/messages",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"from": "Your App <you@yourdomain.com>",
"to": "customer@example.com",
"subject": "Welcome aboard",
"template_key": "brand-layout",
"html": "<p>Hi there, your account is ready.</p>",
},
)
print(response.json())<?php
$payload = [
"from" => "Your App <you@yourdomain.com>",
"to" => "customer@example.com",
"subject" => "Welcome aboard",
"template_key" => "brand-layout",
"html" => "<p>Hi there, your account is ready.</p>",
];
$ch = curl_init("https://api.sendhiiv.com/api/v1/messages");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_KEY",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;use Illuminate\Support\Facades\Http;
$response = Http::withToken('YOUR_API_KEY')->post('https://api.sendhiiv.com/api/v1/messages', [
'from' => 'Your App <you@yourdomain.com>',
'to' => 'customer@example.com',
'subject' => 'Welcome aboard',
'template_key' => 'brand-layout',
'html' => '<p>Hi there, your account is ready.</p>',
]);
return $response->json();using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
var payload = new {
from = "Your App <you@yourdomain.com>",
to = "customer@example.com",
subject = "Welcome aboard",
template_key = "brand-layout",
html = "<p>Hi there, your account is ready.</p>"
};
var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.sendhiiv.com/api/v1/messages", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
payload, _ := json.Marshal(map[string]string{
"from": "Your App <you@yourdomain.com>",
"to": "customer@example.com",
"subject": "Welcome aboard",
"template_key": "brand-layout",
"html": "<p>Hi there, your account is ready.</p>",
})
req, _ := http.NewRequest("POST", "https://api.sendhiiv.com/api/v1/messages", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require "net/http"
require "json"
uri = URI("https://api.sendhiiv.com/api/v1/messages")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
from: "Your App <you@yourdomain.com>",
to: "customer@example.com",
subject: "Welcome aboard",
template_key: "brand-layout",
html: "<p>Hi there, your account is ready.</p>"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.bodyimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendEmail {
public static void main(String[] args) throws Exception {
String body = """
{
"from": "Your App <you@yourdomain.com>",
"to": "customer@example.com",
"subject": "Welcome aboard",
"template_key": "brand-layout",
"html": "<p>Hi there, your account is ready.</p>"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.sendhiiv.com/api/v1/messages"))
.header("Authorization", "Bearer YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}Request body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | array | required | Recipient email address, array, or comma-separated list. |
subject | string | conditional | Subject line. If you pass one, Sendhiiv uses it. A message template subject is only used when this is omitted. |
html | string | optional | Email HTML. With a layout template, this is placed inside the layout. With a message template, it fills {{content}} when that token exists. |
text | string | optional | Plain text body. Required if html and template_key are both omitted. |
from | string | optional | Display sender. Verified-domain accounts send from their own domain; others use the shared sender. |
reply_to | string | optional | Reply address for recipient responses. |
template_key | string | optional | Readable key from a saved layout or message template, for example brand-layout or welcome-offer. |
variables | object | optional | Values for merge tags such as {{firstName}}, {{companyName}}, and {{planName}}. |
attachments | array | optional | Files to attach. Each item: { filename, content (base64), content_type }. 10 MB total per message. |
send_mode | string | optional | Use drip to schedule recipients in batches instead of sending every recipient immediately. |
batch_size | number | optional | Drip mode only. Number of recipients per batch. Defaults to 50, maximum 500. |
batch_interval_minutes | number | optional | Drip mode only. Minutes between batches. Defaults to 15, maximum 1440. |
Responses
{
"success": true,
"status": "queued",
"code": "QUEUED_FOR_DELIVERY",
"message": "1 email(s) queued for delivery",
"total": 1,
"data": [
{ "id": "msg_6ad2009154c402f10b8caf8e", "to": "jane@example.com" }
],
"retry": {
"automatic": true,
"retryable_temporary_failures": true
}
}{
"success": false,
"error": "to is required"
}{
"success": false,
"error": "Content blocked for high-risk promotional/spam patterns: high-risk terms; suspicious financial offer",
"code": "CONTENT_COMPLIANCE_BLOCKED",
"compliance": {
"score": 101,
"severity": "high",
"reasons": ["High-risk terms: lottery, free money", "suspicious financial offer"]
}
}Sendhiiv reviews message content automatically during send. If content is blocked, the email is not sent and the response includes the reasons your app can show or log. A 202 means the message is queued — Sendhiiv retries temporary delivery failures automatically, so your app does not need its own delivery retry loop.
Plan and quota errors (402, 403, 429 quota) return the message in a msg field instead of error; both shapes always include a machine-readable code when one applies.
Message ids & status
Every accepted recipient gets its own id in the data array of the send response, in request order. Store it: the same id arrives as message_id in every webhook event for that message, and you can ask for the message's current state at any time.
curl https://api.sendhiiv.com/api/v1/messages/msg_6ad2009154c402f10b8caf8e \
-H "Authorization: Bearer $SENDHIIV_API_KEY"{
"success": true,
"data": {
"id": "msg_6ad2009154c402f10b8caf8e",
"to": "jane@example.com",
"subject": "Your receipt",
"status": "delivered",
"mode": "live",
"source": "api",
"provider_message_id": "<abc123@yourdomain.com>",
"reason": null,
"bounce_category": null,
"opens": 1,
"clicks": 0,
"created_at": "2026-10-16T10:46:53.522Z",
"updated_at": "2026-10-16T10:47:11.904Z"
}
}status is queued until the message is handed to a provider, then delivered, bounced, failed, suppressed (never sent — the address is on your suppression list) or blocked (sending paused for the account). Webhooks are the push version of this endpoint; use this one to reconcile after a timeout or a missed event.
Idempotency
If a send is accepted but the response never reaches you — a timeout, a dropped connection — retrying blind would deliver the message twice. Send an Idempotency-Key header with any unique string and the retry is safe: you get back the original response, with the same message ids, and nothing further is sent.
curl -X POST https://api.sendhiiv.com/api/v1/messages \
-H "Authorization: Bearer $SENDHIIV_API_KEY" \
-H "Idempotency-Key: order-5521-receipt" \
-H "Content-Type: application/json" \
-d '{"to":"jane@example.com","subject":"Your receipt","html":"<p>Thanks!</p>"}'A replayed response carries Idempotency-Replayed: true. Keys are remembered for 24 hours and scoped to your account, so derive them from something stable in your own system — an order id, an invoice number, a job id — rather than a random value per attempt.
Reusing a key with a different request body returns 422 IDEMPOTENCY_KEY_REUSED: that is a different message and needs its own key. A request that is rejected frees its key immediately, so you can fix the payload and retry with the same one. A request still in flight returns 409 — wait and retry.
Test mode
A key beginning sh_test_ lets you exercise the full integration without sending mail. Create one from API keys in your dashboard by choosing the Test environment, then use it exactly like a live key.
{
"success": true,
"status": "accepted",
"mode": "test",
"code": "TEST_MODE_ACCEPTED",
"message": "2 email(s) accepted in test mode — nothing was delivered",
"total": 2,
"data": [
{ "id": "msg_6ad200bb54c402f10b8caff0", "to": "jane@example.com", "status": "delivered" },
{ "id": "msg_6ad200bb54c402f10b8caff3", "to": "bounced@olddata.com", "status": "suppressed" }
]
}A test send runs every check a live one does — plan, required fields, template rendering, attachment limits, sender and domain resolution, your suppression list and content compliance — so the errors you see are the errors you would get in production. It then stops before delivery.
Test sends return real ids you can look up, and they fire your webhooks with "mode": "test" in the payload, so a handler can be verified end to end. They spend no quota and are kept out of your delivery statistics and sender reputation entirely. Test messages are retained for 7 days.
Suppressions
Your suppression list is the set of addresses Sendhiiv will not send to again. Hard bounces, spam complaints, unsubscribes and failed validations are added automatically and enforced on every send, including sends made with an API key — a suppressed recipient produces an email.dropped event rather than a delivery attempt.
# What is on the list
curl "https://api.sendhiiv.com/api/v1/suppressions?limit=100&reason=bounce" \
-H "Authorization: Bearer $SENDHIIV_API_KEY"
# Add one you learned about yourself
curl -X POST https://api.sendhiiv.com/api/v1/suppressions \
-H "Authorization: Bearer $SENDHIIV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com","reason":"unsubscribe","details":"Asked by reply"}'
# Move a list over from another provider — SendGrid exports work as-is
curl -X POST https://api.sendhiiv.com/api/v1/suppressions/import \
-H "Authorization: Bearer $SENDHIIV_API_KEY" \
-H "Content-Type: text/csv" \
--data-binary @sendgrid-bounces.csvThe import endpoint reads SendGrid's bounce, block, spam-report, invalid-email and unsubscribe exports directly, finding the email column by its header rather than its position, and interpreting a reason or status column when the file has one. Pass reason to label rows that carry none — unsubscribe for a global-unsubscribe export, for instance. Up to 50,000 addresses per request; it reports how many were imported, how many were already listed, and a sample of any unusable rows.
An import never overwrites an existing entry, so it cannot downgrade a complaint we recorded ourselves to a weaker reason. For the same reason, only entries added as manual or invalid can be deleted through the API: a hard bounce or a spam complaint is the receiving side's verdict, and removing it would knowingly damage your own deliverability.
SMS
Send SMS with the same API key you use for email. We send to numbers in Nigeria. Each send is charged from your SMS balance at your tier's price per page; numbers the network rejects are refunded. Turn SMS on and top up from Billing → SMS in your dashboard.
curl -X POST https://api.sendhiiv.com/api/v1/sms/messages \
-H "Authorization: Bearer $SENDHIIV_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4521-shipped" \
-d '{
"to": ["08031234567", "+2349012345678"],
"message": "Your order #4521 has shipped.",
"reference": "order_4521"
}'// Node: npm install sendhiiv
const { Sendhiiv } = require("sendhiiv");
const sendhiiv = new Sendhiiv(process.env.SENDHIIV_API_KEY);
const { data } = await sendhiiv.sms.send({
to: "08031234567",
message: "Your Lagos Bloom code is 418302",
});// .NET: dotnet add package Sendhiiv
var batch = await sendhiiv.Sms.SendAsync(new SendSmsParams
{
To = { "08031234567" },
Message = "Your Lagos Bloom code is 418302",
});<?php // PHP, no package needed
$ch = curl_init("https://api.sendhiiv.com/api/v1/sms/messages");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("SENDHIIV_API_KEY"),
"Content-Type: application/json",
"Idempotency-Key: " . bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "08031234567",
"message" => "Your Lagos Bloom code is 418302",
]),
]);
$result = json_decode(curl_exec($ch), true);# Python: pip install requests
import os, uuid, requests
r = requests.post(
"https://api.sendhiiv.com/api/v1/sms/messages",
headers={
"Authorization": f"Bearer {os.environ['SENDHIIV_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"to": "08031234567", "message": "Your Lagos Bloom code is 418302"},
)
print(r.json())Request body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | string[] | yes | One number or up to 1,000. Use the international form, such as +2348031234567; local forms like 08031234567 also work. Numbers come back in international form, and numbers in countries we don't send to yet are returned in rejected. |
message | string | yes | Up to 6 pages. A page is 160 characters, or 70 if the message has emoji or ₦. |
type | string | no | "transactional" (default) for OTPs, alerts and receipts: reaches numbers on the DND list. "promotional" is cheaper, doesn't reach DND numbers, and networks hold it outside 8am–8pm. |
from | string | no | An approved sender ID on your account. Leave it out to send from the default sender ID. |
reference | string | no | Your own id (an order number, a user id), up to 100 characters. Returned with the message and filterable. |
metadata | object | no | Up to 20 keys / 2 KB of your own data, returned with the message. |
Response
202 with one id per number accepted. Numbers that couldn't be used don't stop the send: they're listed in rejected and not charged. Money is always { "amount", "currency" } in kobo, so 1500 is ₦15.00.
{
"success": true,
"data": {
"object": "sms_batch",
"batch_id": "smsb_5b1e2c4a-9f0d-4c55-8a7e-2f6b1d3c9e10",
"type": "transactional",
"reference": "order_4521",
"messages": [
{ "id": "sms_6740a1b2c3d4e5f6a7b8c9d0", "to": "+2348031234567", "status": "queued", "pages": 1 },
{ "id": "sms_6740a1b2c3d4e5f6a7b8c9d1", "to": "+2349012345678", "status": "queued", "pages": 1 }
],
"rejected": [],
"recipients": 2,
"pages_per_message": 1,
"encoding": "GSM-7",
"cost": { "amount": 1500, "currency": "NGN" },
"balance": { "amount": 4266500, "currency": "NGN" },
"test": false
}
}Checking on a message
# One message: queued → sent → delivered, or failed / rejected
curl https://api.sendhiiv.com/api/v1/sms/messages/sms_6740a1b2c3d4e5f6a7b8c9d0 \
-H "Authorization: Bearer $SENDHIIV_API_KEY"
# Search, newest first. Page with next_cursor until has_more is false.
curl "https://api.sendhiiv.com/api/v1/sms/messages?reference=order_4521&status=failed&limit=50" \
-H "Authorization: Bearer $SENDHIIV_API_KEY"
# Balance, price per page on your tier, and today's daily limit
curl https://api.sendhiiv.com/api/v1/sms/balance \
-H "Authorization: Bearer $SENDHIIV_API_KEY"Treat any status you don't recognise as still pending: new statuses may be added, existing ones are never renamed.
Test numbers
With a sh_test_ key, SMS sends run every check and return the real price, but send nothing and charge nothing. These numbers act out each outcome, so you can test your error handling before going live:
| Number | Result |
|---|---|
08000000001 | delivered |
08000000002 | failed |
08000000003 | rejected (DND) |
| any other number | delivered |
Test messages can be looked up with the test key for 30 days and never appear in your dashboard, balance or daily limit.
SMS errors
| HTTP | Code | Meaning |
|---|---|---|
400 | SMS_INVALID_RECIPIENTS | No usable numbers in to. The response lists each one in rejected, with the reason. |
400 | SMS_MESSAGE_TOO_LONG | More than 6 pages. |
400 | SMS_SENDER_ID_NOT_APPROVED | from isn't an approved sender ID on your account. |
400 | SMS_TOO_MANY_RECIPIENTS | More than 1,000 numbers in one request. Split the send. |
402 | SMS_INSUFFICIENT_BALANCE | Your SMS balance can't cover the send. Includes cost, balance and short_by. |
403 | SMS_NOT_ENABLED | SMS isn't available on your account yet. |
403 | SMS_API_NOT_ON_TIER | Your SMS tier doesn't include API access. |
429 | SMS_DAILY_LIMIT | Your tier's daily page limit is reached. It resets at midnight Lagos time. |
429 | RATE_LIMITED | More than 100 SMS requests a minute on this API key. |
503 | SMS_UNAVAILABLE | Temporarily unavailable. Safe to retry with the same Idempotency-Key. |
Retrying is safe with an Idempotency-Key: the retry returns the original response and nobody is texted or charged twice. The official SDKs add a key to every SMS send for you.
Verify (one-time codes)
Send a login or confirmation code by SMS and check what your user types. Sendhiiv creates the code, texts it, expires it and checks it, so you never generate or store codes yourself. Each code costs one transactional SMS.
# 1. Text a code
curl -X POST https://api.sendhiiv.com/api/v1/verify \
-H "Authorization: Bearer $SENDHIIV_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "08031234567", "app_name": "Lagos Bloom" }'
# → { "data": { "id": "vrf_6740a1b2c3d4e5f6a7b8c9d0", "status": "pending", "expires_at": "…" } }
# SMS: "418302 is your Lagos Bloom verification code. It expires in 10 minutes. Don't share it with anyone."
# 2. Check what the user typed
curl -X POST https://api.sendhiiv.com/api/v1/verify/check \
-H "Authorization: Bearer $SENDHIIV_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "id": "vrf_6740a1b2c3d4e5f6a7b8c9d0", "code": "418302" }'
# → { "data": { "valid": true, "result": "approved", "status": "approved", … } }// Node
const { data } = await sendhiiv.verify.send({ to: "08031234567", appName: "Lagos Bloom" });
// later, when the user types the code:
const { data: check } = await sendhiiv.verify.check({ id: data.id, code: typedCode });
if (!check.valid) throw new Error(check.result); // "incorrect", "expired", …Check by id, or send to instead to check the latest code sent to that number. Optional fields when sending: code_length (4–8, default 6), expires_in_minutes (1–30, default 10), and message, your own text with {code} where the code goes (and optionally {minutes}, {app_name}).
Check results
A check always answers 200. Use valid to decide; result says why not.
| result | Meaning |
|---|---|
approved | Right code. valid is true. A code works once. |
incorrect | Wrong code. attempts_remaining says how many tries are left. |
max_attempts | 5 wrong tries. Send a new code. |
expired | Too late. Send a new code. |
canceled | A newer code was sent to this number, or it was cancelled. |
already_approved | This code was already used. |
Built-in protection
- Codes are stored only as a secure hash, so not even Sendhiiv can read them.
- Each code allows 5 tries, counted safely even when guesses arrive at once.
- A new code to the same number cancels the old one.
- A number can get at most 3 codes every 10 minutes (
429 VERIFY_RATE_LIMITED, withretry_after_seconds), so nobody can use your sign-in form to drain your balance or flood a phone. - Codes go out first in the queue, ahead of bulk messages, and reach numbers on the DND list.
With a sh_test_ key nothing is sent or charged and the code is always 000000. Don't retry a check automatically: each retry uses up one of your user's attempts. Also available: GET /verify/{id} and POST /verify/{id}/cancel.
Webhooks
Add an endpoint under Webhooks in your dashboard and Sendhiiv will POST a JSON event to it as messages are delivered, bounce, or are opened. Each endpoint gets its own signing secret.
Events
| Event | Fires when |
|---|---|
email.delivered | The recipient's mail server accepted the message. |
email.bounced | The recipient's mail server rejected the message. |
email.complained | The recipient marked the message as spam. |
email.dropped | Accepted by the API, then not sent — the address was on your suppression list or was rejected as invalid. |
email.failed | The message could not be sent at all, after all send retries. |
email.opened | The recipient opened the message (tracking must be on). |
email.clicked | The recipient clicked a tracked link. |
sms.sent | The mobile network accepted the SMS. |
sms.delivered | The SMS reached the phone. |
sms.failed | The network couldn't deliver it (phone off, out of coverage…). Not charged if it was never billed. |
sms.rejected | Refused, e.g. a DND number on a promotional send, or an invalid number. Not charged. |
sms.balance_low | A send took your SMS balance below your alert amount (Billing → SMS, ₦1,000 by default). |
SMS events appear once SMS is on for your account. Their payload carries sms_id, batch_id, to, type, status, pages, cost, error, source (dashboard, api, verify), your reference and metadata. The message text is never included, so login codes never leave Sendhiiv. Each status is sent once per message, and test-key sends fire sms.sent then the outcome with "mode": "test".
Payload
{
"id": "email.delivered:64f0c1a2e3b4d5f6a7b8c9d0",
"event": "email.delivered",
"created_at": "2026-08-11T10:15:04.000Z",
"data": {
"message_id": "msg_6ad2009154c402f10b8caf8e",
"provider_message_id": "<abc123@yourdomain.com>",
"messageId": "<abc123@yourdomain.com>",
"to": "recipient@example.com",
"subject": "Welcome aboard",
"status": "delivered",
"campaignId": "64f0bb91e3b4d5f6a7b8c9c1",
"timestamp": "2026-08-11T10:15:04.000Z"
}
}message_id is the id the send response returned for that recipient — the field to correlate on. provider_message_id is the SMTP Message-ID assigned by the delivery system, and messageId is the same value under its original name, kept for existing integrations. Bounce, complaint, failure and dropped events add a reason; email.dropped also adds suppression_reason; email.clicked adds the url that was clicked.
Verifying the signature
Every request carries these headers. Verify Sendhiiv-Signature-V2 against the raw request body before trusting the event.
| Header | Value |
|---|---|
Sendhiiv-Signature-V2 | v1=<hex> — HMAC-SHA256 of timestamp + "." + body, keyed with your signing secret. |
Sendhiiv-Timestamp | Unix seconds when the request was signed. |
Sendhiiv-Event | Event name, e.g. email.delivered. |
Sendhiiv-Event-Id | Stable id for the event. Use it to make your handler idempotent. |
Sendhiiv-Attempt | Attempt number, starting at 1. |
Sendhiiv-Signature | Legacy HMAC-SHA256 of the body alone, without a timestamp. Kept for existing integrations — prefer Sendhiiv-Signature-V2. |
const crypto = require("crypto");
// Raw body — verify before parsing JSON.
app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const secret = process.env.SENDHIIV_WEBHOOK_SECRET;
const timestamp = req.header("Sendhiiv-Timestamp");
const signature = req.header("Sendhiiv-Signature-V2"); // "v1=<hex>"
// Reject anything older than five minutes so a captured request
// cannot be replayed later.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.status(400).send("Stale timestamp");
}
const expected =
"v1=" +
crypto
.createHmac("sha256", secret)
.update(timestamp + "." + req.body.toString())
.digest("hex");
const ok =
signature &&
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return res.status(401).send("Bad signature");
const event = JSON.parse(req.body.toString());
console.log(event.event, event.data.to);
// Respond 2xx quickly; do the real work afterwards.
res.sendStatus(200);
});Retries & delivery
Return any 2xx to acknowledge an event. A 5xx, a timeout, a 408 or a 429 is retried with exponential backoff; any other 4xx is treated as a permanent rejection and is not retried. Requests time out after 10 seconds, so acknowledge first and process afterwards.
Every attempt is recorded in the delivery history on the Webhooks page, with the response status and error. An endpoint that fails persistently is paused automatically — resume it from the same page once it is healthy. Events can be delivered more than once, so key your handler on Sendhiiv-Event-Id. Endpoints must be publicly reachable addresses; private and loopback addresses are rejected.
Rate limits & error codes
The API accepts up to 100 send requests per minute and 600 read requests per minute per IP address. Rate-limited responses return 429 with standard RateLimit-* headers — wait and retry. A single request can carry many recipients in to, so batching recipients is cheaper than looping requests. Monthly sending volume is set by your plan; new domains warm up gradually before reaching full plan volume.
| HTTP | Code | Meaning |
|---|---|---|
202 | QUEUED_FOR_DELIVERY | Success — message(s) accepted and queued. |
202 | TEST_MODE_ACCEPTED | Success — validated with a test key and deliberately not delivered. |
400 | — | Invalid request, e.g. to is missing or no content provided. |
400 | INVALID_ATTACHMENTS | An attachment is malformed or not base64. |
400 | CONTENT_COMPLIANCE_BLOCKED | Content blocked by automatic review. Response includes a compliance object with the reasons. |
401 | — | Missing, invalid, or revoked API key. |
402 | INSUFFICIENT_CREDITS | Pay-as-you-go balance is empty. Top up to continue sending. |
403 | UPGRADE_REQUIRED | Your current plan does not include API access. |
409 | IDEMPOTENT_REQUEST_IN_PROGRESS | A request with the same Idempotency-Key is still being processed. Retry in a moment. |
413 | ATTACHMENT_TOO_LARGE | Attachments exceed 10 MB total. |
422 | IDEMPOTENCY_KEY_REUSED | That Idempotency-Key was already used with a different request body. Use a new key. |
429 | QUOTA_EXCEEDED | Monthly plan email quota reached, or the per-minute request rate limit was exceeded. |
500 | — | Internal error. Safe to report; do not blind-retry sends. |
Retry guidance: 429 rate-limit responses are always safe to retry — they are rejected before anything is queued. A 5xx, a timeout or a network failure is only safe to retry if you sent an Idempotency-Key, since the message may already have been accepted; with a key, the retry returns the original response instead of sending again.