API ReferenceSMS API
Templates
GET/POST/PATCH/DELETE /v1/templates - Saved message templates with merge fields, categories, transactional or promotional type, team or private visibility, and a starter pack.
Templates are named, reusable messages. Use them in the composer, in
campaigns (template_id) and in the
personalised batch API. Template
text uses merge fields: {first_name}, {amount|0} (with a fallback) or the
older {{amount}}. Keys need send to write and query to read.
Template object
{
"id": 12,
"name": "Payment reminder",
"text": "Hi {first_name|there}, a reminder that your payment of {currency|KES} {amount} is due on {due_date}.",
"category": "reminder",
"message_type": "transactional",
"description": "A friendly nudge before a payment is due.",
"variables": ["first_name", "currency", "amount", "due_date"],
"visibility": "team",
"sender_id": null,
"created_by": "ops@example.com",
"starter_key": "payment-reminder",
"use_count": 3,
"encoding": "GSM7",
"segments": 1,
"created_at": "2026-10-22T08:00:00+00:00",
"updated_at": "2026-10-22T08:00:00+00:00"
}| Field | Description |
|---|---|
category | reminder, bank_alert, otp, delivery, appointment, payment_due, promotion, event, other. |
message_type | transactional or promotional (promotional sends add the opt-out line and respect quiet hours). |
visibility | team (everyone in the workspace) or private (only its creator sees and edits it). |
variables | Merge fields used in text. |
encoding / segments | For the template text as written (merge-field values change the real length). |
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/templates | List team templates and your private ones. Filters: category, message_type, q, limit (max 500). Also returns categories. |
POST | /v1/templates | {name, text, category?, message_type?, description?, visibility?, sender_id?} - 201. |
GET | /v1/templates/{id} | One template. |
PATCH | /v1/templates/{id} | Partial update - send only the fields to change. |
DELETE | /v1/templates/{id} | 204 No Content. |
GET | /v1/templates/starter-pack | Ready-made templates (see below). |
POST | /v1/templates/starter-pack/{key} | Copy a starter into your library (201; returns the existing copy if you already added it). |
POST | /v1/templates/render | {text, vars?, name?, phone?} - returns text, missing, encoding, segments, chars, variables, gsm_suggestions. Nothing is sent. |
Errors: 400 invalid_category, invalid_message_type, invalid_visibility;
404 not_found (also for another member's private template).
Starter pack
| Key | Category | Type | Name |
|---|---|---|---|
payment-reminder | reminder | transactional | Payment reminder |
renewal-reminder | reminder | transactional | Subscription renewal |
debit-alert | bank_alert | transactional | Debit alert |
credit-alert | bank_alert | transactional | Credit alert |
card-transaction | bank_alert | transactional | Card transaction alert |
login-code | otp | transactional | Login code |
transaction-otp | otp | transactional | Transaction authorisation code |
out-for-delivery | delivery | transactional | Out for delivery |
ready-for-pickup | delivery | transactional | Ready for pickup |
appointment-reminder | appointment | transactional | Appointment reminder |
loan-repayment | payment_due | transactional | Loan repayment due |
school-fees | payment_due | transactional | School fees balance |
invoice-overdue | payment_due | transactional | Invoice overdue |
weekend-sale | promotion | promotional | Weekend sale |
loyalty-points | promotion | promotional | Loyalty points balance |
event-invite | event | promotional | Event invite |
event-reminder | event | transactional | Event reminder (registered guests) |
For one-time passwords with automatic expiry and checking, use the Verify API instead of a template.
Example
curl -X POST https://sms.esmsafrica.io/v1/templates \
-H "Authorization: Bearer $ESMS_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Fee balance", "text": "Dear parent, {student_name}'"'"'s fee balance is UGX {balance}.",
"category": "payment_due", "message_type": "transactional"}'
curl -X POST https://sms.esmsafrica.io/v1/templates/starter-pack/debit-alert \
-H "Authorization: Bearer $ESMS_API_KEY"// SDK 1.2.0 or later
const t = await esms.templates.create({ name: "Fee balance", text: "Dear parent, {student_name}'s fee balance is UGX {balance}.",
category: "payment_due", messageType: "transactional" });
const debit = await esms.templates.useStarter("debit-alert");
const preview = await esms.templates.render({ text: t.text, vars: { student_name: "Ada", balance: "150,000" } });# SDK 1.2.0 or later
t = esms.templates.create(name="Fee balance", text="Dear parent, {student_name}'s fee balance is UGX {balance}.",
category="payment_due", message_type="transactional")
debit = esms.templates.use_starter("debit-alert")
preview = esms.templates.render(t["text"], vars={"student_name": "Ada", "balance": "150,000"})// SDK 1.2.0 or later
$t = $esms->templates->create(['name' => 'Fee balance', 'text' => "Dear parent, {student_name}'s fee balance is UGX {balance}.",
'category' => 'payment_due', 'message_type' => 'transactional']);
$debit = $esms->templates->useStarter('debit-alert');
$preview = $esms->templates->render($t['text'], ['vars' => ['student_name' => 'Ada', 'balance' => '150,000']]);// SDK 1.2.0 or later
t, _ := client.Templates.Create(ctx, esms.JSON{"name": "Fee balance",
"text": "Dear parent, {student_name}'s fee balance is UGX {balance}.", "category": "payment_due"})
debit, _ := client.Templates.UseStarter(ctx, "debit-alert")
preview, _ := client.Templates.Render(ctx, t["text"].(string), map[string]string{"student_name": "Ada", "balance": "150,000"})