Upgrading from v0 to v1

API v1 builds on v0's simple authentication and TTL guarantees while introducing approved SMS templates, idempotency keys, and status lookup endpoints. Both /api/v0 and /api/v1 can be used with the same App ID and Secret Key.

Overview of Changes

Template-Verified Messaging: Every SMS sent via /api/v1/sms/send or /api/v1/sms/bulk is associated with an approved template (either organization-specific or public).
Priority & Pricing Moved to Templates: Instead of passing type (critical | standard | bulk) on every request, priority and tokenMultiplier are configured on the approved template.
Drop-in Compatibility for Raw Messages: If you don't want to refactor your app to send template + params immediately, you can still send a raw message string in v1 — Emess will automatically match it against your approved templates' compiled regex rules.

v0 vs v1 Comparison

Capability	API v0 (`/api/v0`)	API v1 (`/api/v1`)
Authentication	`POST /api/v0/auth/token`	`POST /api/v1/auth/token` (identical payload)
Message Content	Arbitrary raw `message` string	`template` + `params`, or raw `message` matching an approved template
Priority Tier (TTL)	Passed in request body as `type`	Determined automatically from the template's `priorityTier`
Token Cost	`segments × 1`	`ceil(segments × template.tokenMultiplier)`
Idempotency	Not supported	Supported via `Idempotency-Key` header
Delivery Status API	Dashboard only	`GET /messages`, `GET /sms/:id`, `GET /batches`, and `GET /batches/:id` (replaces deprecated `GET /sms/batches/:id`)

Sending SMS: v0 vs v1

In v0, you passed the full text and priority tier directly in the request body:

v0: POST /api/v0/sms/send

{
  "number": "+243990000000",
  "message": "Your verification code is 482910",
  "type": "critical"
}

In v1, you have two ways to send the same message once your template (e.g. otp_login with text Your verification code is {code}) is approved:

Option A: Explicit Template Slug + Parameters (Recommended)

v1: POST /api/v1/sms/send

{
  "number": "+243990000000",
  "template": "otp_login",
  "params": {
    "code": "482910"
  }
}

Option B: Raw Message Matching (Zero-Refactor Migration)

If you omit template and pass message, Emess tests your string against your organization's approved templates (and public templates) and validates any captured placeholders against the template's paramRules:

v1: POST /api/v1/sms/send (raw message mode)

{
  "number": "+243990000000",
  "message": "Your verification code is 482910"
}

Both options return the enriched v1 response including the matched template slug, resolved priority type, and token cost:

Response (200 OK)

{
  "message": "SMS sent successfully",
  "id": "msg_uuid",
  "batchId": "batch_uuid",
  "template": "otp_login",
  "type": "critical",
  "cost": 1
}

Idempotency Keys

In v1, both POST /api/v1/sms/send and POST /api/v1/sms/bulk accept an optional Idempotency-Key HTTP header. If you retry a request with the same key for the same billing organization, Emess returns the original batch/message IDs with "idempotent": true without deducting tokens or sending a duplicate SMS.

New Endpoints in v1

POST /api/v1/templates — Register or update a pending template.
GET /api/v1/templates — List your organization's templates and approved public templates.
GET /api/v1/templates/:slug — Inspect a single template and its parameter rules.
PATCH /api/v1/templates/:slug — Partially update an unapproved organization template.
DELETE /api/v1/templates/:slug — Delete an organization template.
GET /api/v1/messages — Cursor-paginated list of outbound SMS messages.
GET /api/v1/sms/:id — Retrieve status and batch details for a single message.
GET /api/v1/batches and GET /api/v1/batches/:id — List and inspect batches (replaces the deprecated GET /api/v1/sms/batches/:id alias).
GET /api/v1/balance & GET /api/v1/ledger — Inspect active token buckets and paginated ledger entries.
/api/v1/webhooks/* — Manage app-scoped webhook endpoints and inspect delivery logs.

Introduction Authentication