API reference

Evenza Gateway docs

Base URL: https://api.evenza.net

Live WhatsApp sendLive SMS sendLive Email / SMTP

Overview / Getting started

Authenticate with your API key, then call POST /api/v1/send for WhatsApp, SMS, or email. Start with the OTP quick start if you only need verification codes.

Authentication

All /api/v1/* endpoints (except health) require your product API key:

header

Authorization: Bearer YOUR_API_KEY

Get a key from Sign up or your developer dashboard. Keys start with evz_ and are shown once at creation / regenerate.

Invalid or missing keys return 401 Unauthorized.

Send message — POST /api/v1/send

Send via an active Gateway channel. Request body is a discriminated union on channel.

WhatsApp Live

Template-based send (Meta Cloud API). templateName must be an approved WhatsApp template. Variables map to body placeholders by position ("1", "2", …). Optional senderRef selects a dedicated WhatsApp account for your product; omit it (or unknown ref) to use the platform shared default.

IMAGE / VIDEO / DOCUMENT headers need a public HTTPS URL (headerImage or variables["header.image"]) or a Meta media id from POST /{phone_number_id}/media: headerImageId, headerVideoId, or headerDocumentId. Meta CDN example URLs (scontent / lookaside / fbcdn / whatsapp.net) are rejected. Missing media for such templates returns 400.

curl

curl -X POST https://api.evenza.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "recipient": "923001234567",
    "templateName": "otp_verification",
    "language": "en",
    "variables": { "1": "482913" },
    "senderRef": "test-client-1"
  }'

IMAGE-header template (public URL or media id)

curl

curl -X POST https://api.evenza.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "recipient": "923001234567",
    "templateName": "flash_sale",
    "language": "en",
    "variables": { "1": "Ali", "2": "20", "3": "Aug 20" },
    "headerImage": "https://evenza.net/og-image.png"
  }'

# Or with a Meta media id (from POST /{phone_number_id}/media):
#   "headerImageId": "MEDIA_ID_FROM_META"

Success (200)

json

{
  "ok": true,
  "product": "your-product-slug",
  "account": {
    "id": "…",
    "mode": "dedicated",
    "senderRef": "test-client-1",
    "phoneNumberId": "…"
  },
  "meta": { /* Meta Cloud API response */ }
}

Error (400) — media header without valid image

json

{
  "ok": false,
  "product": "your-product-slug",
  "error": "IMAGE header requires a public HTTPS URL (headerImage / variables[\"header.image\"]) or a Meta media id (headerImageId). Meta CDN example URLs cannot be used.",
  "meta": { "error": { "message": "…" } }
}

SMS Live

Plain-text SMS via the Gateway's configured SMS provider. Pass the full message body.

curl

curl -X POST https://api.evenza.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "recipient": "923001234567",
    "message": "Your verification code is 482913. It expires in 5 minutes."
  }'

Success (200)

json

{
  "ok": true,
  "product": "your-product-slug",
  "provider": { /* provider request/response details */ }
}

Email / SMTP Live

Sends through the Gateway's active SMTP integration. Use channel: "email" (or "smtp"). recipient must be a valid email address. Optional html body is supported alongside plain-text message.

curl

curl -X POST https://api.evenza.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "recipient": "user@example.com",
    "subject": "Your verification code",
    "message": "Your Evenza code is 482913. Valid for 5 minutes."
  }'

Success (200)

json

{
  "ok": true,
  "product": "your-product-slug",
  "provider": { "message": "Email sent" }
}

Templates (WhatsApp)

Live

Manage WhatsApp message templates for your product. SMS and email do not use this API.

POST /api/v1/templates — submit new template

curl

curl -X POST https://api.evenza.net/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "otp_verification",
    "category": "AUTHENTICATION",
    "language": "en",
    "components": [
      {
        "type": "BODY",
        "text": "Your verification code is {{1}}."
      }
    ]
  }'

Returns 201 with the stored template record and Meta response when creation succeeds.

GET /api/v1/templates — list all

curl

curl https://api.evenza.net/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "ok": true,
  "product": "your-product-slug",
  "templates": [
    {
      "id": "clx...",
      "name": "otp_verification",
      "category": "AUTHENTICATION",
      "language": "en",
      "status": "APPROVED"
    }
  ]
}

GET /api/v1/templates/:id/status — check approval

Refreshes status from Meta for a template that belongs to your product. Unknown IDs return 404.

curl

curl https://api.evenza.net/api/v1/templates/TEMPLATE_RECORD_ID/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Incoming messages — GET /api/v1/messages

Poll inbound WhatsApp messages attributed to your product only (productId from the API key). Other products' rows are never returned.

Query params: since (ISO timestamp — rows with createdAt after this instant, oldest first) and limit (default 50, max 100). Omit since to get the latest page (newest first).

curl

curl "https://api.evenza.net/api/v1/messages?since=2026-08-14T00:00:00.000Z&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success (200)

json

{
  "ok": true,
  "product": "your-product-slug",
  "messages": [
    {
      "id": "clxxxxxxxx",
      "phoneNumber": "15551234567",
      "body": "hello",
      "messageType": "text",
      "providerMessageId": "wamid.xxx",
      "phoneNumberId": "1234567890",
      "createdAt": "2026-08-14T12:00:00.000Z"
    }
  ]
}

Webhooks

Push coming soon

Meta delivers incoming WhatsApp messages and delivery status updates to the Gateway at POST /api/webhooks/whatsapp. Events are verified, matched to a product when possible, and stored on MessageLog with full content. Poll your rows via GET /api/v1/messages.

Push forwarding to your own callback URL is still coming soon.

Error codes

Status	Meaning
401	Missing/invalid API key (`{ "error": "Unauthorized" }`)
400	Invalid JSON or body (wrong channel fields, validation errors)
404	Template not found for your product (status endpoint)
500	Integration config decrypt/invalid on the Gateway
502	Upstream provider failed (Meta / SMS). Body includes `ok: false` and provider payload
503	Channel not configured — no active WhatsApp, SMS, or SMTP integration
429	Rate limit exceeded (per API key). Includes `Retry-After` header — wait and retry

Rate limits

Live

Messaging API (/api/v1/send, /api/v1/templates, template status): 60 requests per minute per API key. Exceeding the limit returns 429 with a Retry-After header (seconds) and a JSON body explaining the limit. Provider (Meta / SMS) limits may still apply upstream.

Developer signup / password reset are rate-limited to 5 attempts per IP per hour (form errors with retry guidance).

Quick start — OTP verification

Most common use case: generate a code in your app, deliver it with Evenza, verify on your side.

Live

curl

curl -X POST https://api.evenza.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "recipient": "923001234567",
    "templateName": "otp_verification",
    "language": "en",
    "variables": { "1": "482913" }
  }'

SMS

Live

curl

curl -X POST https://api.evenza.net/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "recipient": "923001234567",
    "message": "Your Evenza code is 482913. Valid for 5 minutes."
  }'

Store hashed OTPs in your database. Evenza logs delivery status per product — not your OTP secret.

Need a key?

Get API Access