Send Template SMS

Endpoint

POST /api/sms/messages/template

Request body

Field	Type	Required	Description
`template_id`	string	Yes	The template's short name. `template_name` is accepted as an alias; if both are sent, `template_id` wins
`sender`	string	Yes	Sender ID (max 11 alphanumeric chars)
`payment_type`	string	Yes	`wallet` or `subscription`
`receiver`	string	Yes	Phone number matching a provider pattern configured in the platform
`params`	array	Yes	Array of single-key objects mapping placeholder names to values
`expires_after`	integer	No	Seconds this message stays worth delivering, `60`–`604800`. Defaults to 24 hours. Undelivered recipients are then marked `expired` and refunded — see Message validity

Only templates with status active in your project can be used.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_TOKEN`
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`application/json`
`Idempotency-Key`	No	Replaying the same key with the same body returns the original result instead of sending again

Template format

Templates use named placeholders with double curly braces: {{name}}, {{date}}, etc.

Example template

مرحباً {{name}}، تم تأكيد معاينتك للعقار يوم {{date}} الساعة {{time}} في منطقة {{area}}.

Params format

params is an array of single-key objects, one per placeholder:

[
  { "name": "أحمد محمد" },
  { "date": "2024-01-15" },
  { "time": "17:00" },
  { "area": "قرقارش" }
]

Example

curl -X POST https://sms.lamah.com/api/sms/messages/template \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "template_id": "property_viewing",
    "sender": "RealEstate",
    "payment_type": "wallet",
    "receiver": "00218912345678",
    "params": [
      { "name": "أحمد محمد" },
      { "date": "2024-01-15" },
      { "time": "17:00" },
      { "area": "قرقارش" }
    ]
  }'

Response

{
  "message_id": "b9e8a1f2-4c60-4b0b-9f51-0c4f2f6c9e7a",
  "cost": 1
}

Field	Description
`message_id`	UUID for this send — use it with Get Message
`cost`	Number of SMS parts charged for this send, computed from the rendered message

Template sends bypass the manual message-approval queue — they are auto-approved. A 200 still means accepted, not delivered; poll Get Message for status.

Error responses

422 Unprocessable Entity — Validation failed

{
  "message": "The template name field is required.",
  "errors": {
    "template_name": ["The template name field is required."]
  }
}

404 Not Found — Sender not found

{ "message": "Sender not found" }

404 Not Found — Template not found

The short name does not match an active template in this project.

{ "message": "Template not found" }

400 Bad Request — Provider mismatch

The receiver's network is not one the sender ID is registered on. This is a permanent mismatch — retrying will not help.

{ "message": "The receiver is not from the same provider" }

400 Bad Request — Missing parameter

{ "message": "Missing parameter: name" }

400 Bad Request — Parameter too long

Raised when a template parameter has a configured maximum length and the supplied value exceeds it.

{ "message": "Parameter \"name\" exceeds max limit of 20" }

400 Bad Request — Insufficient balance

{ "message": "Insufficient balance" }

401 Unauthorized

{ "message": "Invalid or missing token." }

409 Conflict — Idempotency key reused

{ "message": "Idempotency key is already in use" }

503 Service Unavailable — Provider temporarily unavailable

The receiver's network operator is one your sender ID is registered on, but it is temporarily unreachable. Nothing is sent and nothing is charged.

{ "message": "The provider for this receiver is temporarily unavailable" }

503 Service Unavailable — Ingest unavailable

{ "message": "SMS ingest unavailable" }

If your company is not yet verified, receiver is overridden with your company's registered phone number. The request still returns 200 and still consumes balance.

Templates are created and managed through your dashboard under Messages → Templates. You cannot create templates via the API.

Managing templates

Create and manage your templates from the dashboard under Messages → Templates.

Send Template SMS

On this page