eSMS AfricaeSMS Africa
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"
}
FieldDescription
categoryreminder, bank_alert, otp, delivery, appointment, payment_due, promotion, event, other.
message_typetransactional or promotional (promotional sends add the opt-out line and respect quiet hours).
visibilityteam (everyone in the workspace) or private (only its creator sees and edits it).
variablesMerge fields used in text.
encoding / segmentsFor the template text as written (merge-field values change the real length).

Endpoints

MethodPathDescription
GET/v1/templatesList 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-packReady-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

KeyCategoryTypeName
payment-reminderremindertransactionalPayment reminder
renewal-reminderremindertransactionalSubscription renewal
debit-alertbank_alerttransactionalDebit alert
credit-alertbank_alerttransactionalCredit alert
card-transactionbank_alerttransactionalCard transaction alert
login-codeotptransactionalLogin code
transaction-otpotptransactionalTransaction authorisation code
out-for-deliverydeliverytransactionalOut for delivery
ready-for-pickupdeliverytransactionalReady for pickup
appointment-reminderappointmenttransactionalAppointment reminder
loan-repaymentpayment_duetransactionalLoan repayment due
school-feespayment_duetransactionalSchool fees balance
invoice-overduepayment_duetransactionalInvoice overdue
weekend-salepromotionpromotionalWeekend sale
loyalty-pointspromotionpromotionalLoyalty points balance
event-inviteeventpromotionalEvent invite
event-remindereventtransactionalEvent 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"})

On this page