Sendhiiv API documentation

Send transactional email with a single HTTP call to POST https://api.sendhiiv.com/api/v1/messages, authenticated with a Bearer API key. Prefer SMTP? Point your existing library at the Sendhiiv SMTP relay (smtp.sendhiiv.com, port 587 STARTTLS or 465 TLS) with credentials from your dashboard — no code changes. Create a free account to get an API key (3,000 emails/month free).

Authentication

Send your API key on every request: Authorization: Bearer sh_live_xxxxx. Basic auth is also accepted with username api and the key as password (same format as Mailgun).

Request body (JSON)

to (string | array, required) — recipient address, array, or comma-separated list.
subject (string) — subject line; a message template's subject is only used when this is omitted.
html (string) — HTML body. With a layout template it is placed inside the layout; with a message template it fills {{content}} when present.
text (string) — plain-text body; required if html and template_key are both omitted.
from (string) — display sender, e.g. Acme <hello@yourdomain.com>. Verified-domain accounts send from their own domain; others use the shared sender.
reply_to (string) — Reply-To address.
template_key (string) — key of a saved layout or message template, e.g. brand-layout.
variables (object) — values for merge tags such as {{firstName}}.
attachments (array) — items of { filename, content (base64), content_type }, 10 MB total per message.
send_mode (string) — drip schedules recipients in batches instead of sending all immediately.
batch_size (number) — drip only; recipients per batch (default 50, max 500).
batch_interval_minutes (number) — drip only; minutes between batches (default 15, max 1440).

Success response (HTTP 202)

{
  "success": true,
  "status": "queued",
  "code": "QUEUED_FOR_DELIVERY",
  "message": "1 email(s) queued for delivery",
  "total": 1,
  "retry": { "automatic": true, "retryable_temporary_failures": true }
}

202 means the message is queued; Sendhiiv retries temporary delivery failures automatically, so your app does not need its own delivery retry loop.

Error responses

Errors return { "success": false, "error": "..." } with a machine-readable code when one applies. Plan and quota errors (402, 403, 429 quota) return the text in a msg field instead of error.

400 — invalid request (e.g. to is required); INVALID_ATTACHMENTS; CONTENT_COMPLIANCE_BLOCKED (body includes a compliance object with score, severity and reasons).
401 — missing, invalid, or revoked API key.
402 INSUFFICIENT_CREDITS — pay-as-you-go balance empty.
403 UPGRADE_REQUIRED — plan does not include API access.
413 ATTACHMENT_TOO_LARGE — attachments exceed 10 MB total.
429 — rate limit (100 requests/min per IP, standard RateLimit-* headers) or QUOTA_EXCEEDED when the monthly plan quota is reached.
500 — internal error; do not blind-retry sends.

Retry guidance: only 429 rate-limit responses are safe to retry automatically — they are rejected before anything is queued. Do not auto-retry 5xx or network failures, since the message may already have been accepted. One request can carry many recipients in to, so batching recipients is cheaper than looping requests.

Rate limits

100 API requests per minute per IP. Monthly sending volume is set by your plan; new domains warm up gradually before reaching full plan volume. See pricing for plan volumes.

Official SDKs

Typed request/response objects, error codes surfaced as exception types, and automatic retries for 429 rate limits only (the one failure that can never double-send).

Node.js (18+, zero dependencies, TypeScript definitions included): npm install sendhiiv — npm, GitHub

const { Sendhiiv } = require("sendhiiv");
const sendhiiv = new Sendhiiv(process.env.SENDHIIV_API_KEY);
await sendhiiv.messages.send({
  from: "Acme <hello@yourdomain.com>", // optional — omit to use the shared sender
  to: "customer@example.com",
  subject: "Welcome aboard",
  html: "<p>Your account is ready.</p>",
});

.NET (runs on .NET 10, 9, 8, 6, .NET Core, Mono, and .NET Framework 4.5–4.8; zero dependencies on Framework, TLS 1.2 enabled automatically there): dotnet add package Sendhiiv — NuGet, GitHub

using Sendhiiv;
var sendhiiv = new SendhiivClient(apiKey);
await sendhiiv.Messages.SendAsync(new SendMessageParams
{
    From = "Acme <hello@yourdomain.com>", // optional — omit to use the shared sender
    To = { "customer@example.com" },
    Subject = "Welcome aboard",
    Html = "<p>Your account is ready.</p>",
});

SMTP relay for drop-in migration from any provider — sends are tracked exactly like API sends
Layout and message templates with {{merge}} variables
Same request fields as Resend — migrate in minutes