Introduction
Welcome to the StackVerify API. Use this API to send SMS, Email, and WhatsApp messages programmatically to your customers. All requests are served over HTTPS from a single base URL.
Authentication
All API endpoints require authentication via a Bearer token.
Include your API key in every request using the Authorization header.
You can generate and manage keys from Settings → API Keys.
Required header
Base URL
All API requests must be made to the following base URL.
All endpoints are versioned under /api/v1. HTTPS only — plain HTTP requests will be rejected.
Rate Limiting
Rate limits are enforced per API key based on your subscription tier.
Lite
100
requests / minute
10,000 messages/month
Pro
500
requests / minute
Unlimited messages
Enterprise
Custom
dedicated limits
SLA guaranteed
When a rate limit is exceeded the API returns 429 Too Many Requests.
The response includes a Retry-After header with the number of seconds to wait.
Errors
StackVerify uses conventional HTTP status codes to indicate success or failure.
| Code | Meaning | Description |
|---|---|---|
200 |
OK | Request succeeded. |
201 |
Created | Resource created successfully. |
400 |
Bad Request | Missing or invalid parameters. |
401 |
Unauthorized | Invalid or missing API key. |
403 |
Forbidden | Valid key, but insufficient permissions. |
404 |
Not Found | Resource does not exist. |
422 |
Unprocessable Entity | Validation error — check the errors field. |
429 |
Too Many Requests | Rate limit exceeded. |
500 |
Internal Server Error | Something went wrong on our end. |
All error responses include a JSON body with status, message, and optionally an errors object for validation failures.
Send SMS
/api/v1/sms/send
Send an SMS message to one or more recipients.
Required: sms:send| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
to |
string / array | Required | — | Recipient phone number(s) in E.164 format. Pass an array for bulk sends. |
message |
string | Required | — | The SMS body text. Max 1,600 characters. |
sender_id |
string | Optional | Workspace default | Sender name or number to display. |
callback_url |
string | Optional | — | URL to receive delivery report webhooks. |
scheduled_at |
string | Optional | — | ISO-8601 timestamp to schedule the send. |
Response
200 OKGet SMS Status
/api/v1/sms/status/{messageId}
Retrieve the current delivery status of an SMS message.
Required: sms:readStatus values
| Status | Description |
|---|---|
queued |
Message has been accepted and is queued for delivery. |
sent |
Message has been dispatched to the carrier. |
delivered |
Carrier confirmed delivery to handset. |
failed |
Delivery failed. Check the error_message field. |
undelivered |
Accepted by carrier but not delivered within validity period. |
Response
200 OKList SMS Messages
/api/v1/sms
Returns a paginated list of SMS messages sent from your workspace.
Required: sms:read| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page |
integer | Optional | 1 | Page number. |
per_page |
integer | Optional | 20 | Results per page. Max 100. |
status |
string | Optional | — | Filter by status: queued, sent, delivered, failed. |
from |
string | Optional | — | Filter by ISO-8601 date range start. |
to |
string | Optional | — | Filter by ISO-8601 date range end. |
Send Email
/api/v1/email/send
Send a transactional or marketing email to one or more recipients.
Required: email:send| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
to |
string / array | Required | — | Recipient email(s). Array for batch sending. |
subject |
string | Required | — | Email subject line. |
html |
string | Required | — | HTML body. Required if text is not provided. |
text |
string | Required | — | Plain-text body. Required if html is not provided. |
from_name |
string | Optional | Workspace default | Sender display name. |
from_email |
string | Optional | Workspace default | Sender email address. Must be a verified domain. |
reply_to |
string | Optional | — | Reply-To address. |
attachments |
array | Optional | — | Array of base64-encoded file attachments. |
headers |
object | Optional | — | Custom headers as key-value object. |
scheduled_at |
string | Optional | — | ISO-8601 timestamp to schedule delivery. |
Emails are sent via your connected sending domain. Go to Settings → Email Settings to verify your domain before using this endpoint.
Response
200 OKGet Email Status
/api/v1/email/status/{messageId}
Retrieve delivery and engagement status for a sent email.
Required: email:read| Status | Description |
|---|---|
queued |
Accepted and queued for delivery. |
sent |
Sent to the receiving mail server. |
delivered |
Mail server accepted the message. |
opened |
Recipient opened the email (pixel tracked). |
clicked |
Recipient clicked a tracked link. |
bounced |
Permanently undeliverable address. |
failed |
Delivery failed. See error_message. |
spam |
Reported as spam by recipient. |
WhatsApp API
Send WhatsApp messages programmatically using your API key. All WhatsApp endpoints require the whatsapp:send or whatsapp:read permission on your API key.
All outbound WhatsApp messages must use a pre-approved Meta template.
This is a requirement of the WhatsApp Business API — Meta does not allow businesses to send free-form messages to users who have not messaged them first within the last 24 hours. Every message you initiate must reference an approved template. Templates are submitted to Meta through your StackVerify dashboard under WhatsApp → Templates and typically reviewed within 24 hours.
Send WhatsApp Template Message
/api/v1/whatsapp/send-template
Send an approved Meta template message for bulk or outbound messaging (no 24-hour restriction).
Required: whatsapp:send| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
to |
string | Required | — | Recipient phone number in E.164 format. |
template_name |
string | Required | — | The approved template name from your account. |
language |
string | Required | — | BCP-47 language code e.g. en, sw, fr. |
variables |
object | Optional | — | Key-value pairs where keys are placeholder positions as strings e.g. {"1":"John","2":"ORD-9921"}. |
header_media_url |
string | Optional | — | Public URL of the image or video for templates with a media header. |
The template must be approved by Meta before use. Sending to a non-existent or unapproved template name will return a 422 error.
Response
200 OKGet WhatsApp Message Status
/api/v1/whatsapp/status/{messageId}
Retrieve the current delivery and read status of a WhatsApp message.
Required: whatsapp:readStatus values
| Status | Description |
|---|---|
queued |
Message accepted and queued for delivery. |
sent |
Message dispatched to WhatsApp servers. |
delivered |
Delivered to recipient's device. |
read |
Recipient has opened the message. |
failed |
Delivery failed. Check the error_message field. |
Response
200 OKDelivery Reports
StackVerify will POST delivery reports to your callback URL when the status of a message changes.
Set your callback URL when sending a message using the callback_url parameter, or configure a global default in Settings → Webhooks.
Payload fields
| Field | Type | Description |
|---|---|---|
event |
string | Always delivery_report. |
message_id |
string | StackVerify message ID. |
to |
string | Recipient phone/email. |
status |
string | New status value. |
timestamp |
string | ISO-8601 datetime of the status change. |
channel |
string | sms, email, or whatsapp. |
error_code |
string? | Provider error code if status is failed. |
Inbound Messages
When a recipient replies to your number, StackVerify forwards the inbound message to your configured inbound webhook URL.
| Field | Type | Description |
|---|---|---|
event |
string | Always inbound_message. |
from |
string | Sender phone number. |
to |
string | Your number that received the message. |
message |
string | Raw message text. |
channel |
string | sms or whatsapp. |
received_at |
string | ISO-8601 timestamp. |
Webhook Security
Every webhook request includes an X-StackVerify-Signature header so you can verify authenticity.
Verification algorithm
- Get the raw request body as a string.
- Compute
HMAC-SHA256(rawBody, webhookSecret). - Compare against the value in
X-StackVerify-Signature. - Reject the request if they do not match.
Always verify webhook signatures in production. Never process webhook payloads from untrusted sources.
Code Examples
Quick-start examples for the most common use-cases. Switch languages using the tabs in the panel on the right.
Send your first SMS
Replace YOUR_API_KEY and the recipient number, then run the cURL example shown in the code panel →
Handle delivery reports
Expose a public HTTPS endpoint, pass it as callback_url, and use the webhook security guide to verify each incoming payload.
SDKs & Libraries
Official and community SDKs for faster integration.
Node.js
npm install stackverify
PHP
composer require stackverify/sdk
Python
pip install stackverify
Laravel
composer require stackverify/laravel
SDKs are currently in development. In the meantime, all examples in this reference can be copy-pasted and run directly.
Postman Collection
Import the StackVerify collection into Postman to test every endpoint interactively.
StackVerify API — Postman Collection
All endpoints pre-configured with environment variables for base_url and api_key.
Was this page helpful?
Powered by StackVerify