Templates
Manage the templates an account sends by: its email templates, its SMS headers and DLT templates, and its WhatsApp number and templates. Reading them needs the channel's send scope or templates:manage; changing them needs an Owner or Admin key that holds templates:manage.
These /external/v1 routes use API keys. OAuth access tokens use API v2; the presence of an example does not establish that a deployment is configured for that version.
Email templates
The account's email templates are those of its default workspace, where the API's messages are, as the dashboard lists them there. A template made through the API is HTML, with {{name}} placeholders that a send fills; one designed in the dashboard's editor can be read, sent and deleted, but not replaced, so its HTML and its design never part.
| Method | Path | What it does |
|---|---|---|
GET | /external/v1/templates | The templates, newest first, without their HTML |
GET | /external/v1/templates/{id} | One template, with its HTML and the variables it takes |
POST | /external/v1/templates | Makes a template from HTML: 201 |
PUT | /external/v1/templates/{id} | Replaces a template made from HTML: its name, subject and HTML |
DELETE | /external/v1/templates/{id} | Deletes a template: 204, and it is no longer listed or sent |
- Name
name- Type
- string
- Description
Required: the template's name, at most 255 characters. Oblic's standard name validation also applies; length alone is not sufficient.
- Name
subject- Type
- string
- Description
The subject an email sent by it takes when the send gives none, at most 1,023 characters, with placeholders of its own. An omitted or blank subject is stored as
null; surrounding whitespace is removed from a nonblank subject.
- Name
html- Type
- string
- Description
Required: the HTML, stored as provided, at most 65,535 UTF-8 bytes. Variable values are HTML-escaped when a send fills placeholders; this does not sanitize or sandbox the template's HTML.
Make a template
curl -X POST https://api.oblic.app/external/v1/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Order shipped",
"subject": "Order {{order_id}} is on its way",
"html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>"
}'
201 Created
{
"status": "success",
"data": {
"id": "TEM000R7ZM4Q2VXH00",
"name": "Order shipped",
"subject": "Order {{order_id}} is on its way",
"kind": "html",
"variables": ["order_id", "first_name"],
"html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>",
"createdAt": "2026-10-24T09:30:00Z",
"updatedAt": "2026-10-24T09:30:00Z"
},
"errors": null
}
- A placeholder is
{{name}}: ASCII letters and digits,_,.,-and spaces only inside the name, at most 64 characters.variableslists the ones the subject and HTML hold, ignoring case, in first-appearance order and spelling. kindishtmlfor a template made through the API, anddesignedfor one made in the dashboard's editor. If a template has no subject, provide one with the send; its kind is not a substitute for checking the returned subject.- The dashboard's mentions, such as
@unsubscribeor@organizationName, are filled only by campaigns and automations, recipient by recipient. A send by a template that holds one is refused. - The list pages by
cursorandlimit: 25 per page by default, from 1 to 100, as Pagination describes. Treat the returned cursor as opaque.
| Refused | cd | When |
|---|---|---|
| 400 | TEMPLATE_TOO_LARGE | The HTML is over 65,535 bytes |
| 404 | TEMPLATE_NOT_FOUND | The account has no template with that id |
| 409 | TEMPLATE_DESIGNED | Replacing a template designed in the dashboard's editor |
SMS headers and templates
An SMS goes from a DLT header and matches a DLT content template under Cunomial's configured DLT entity. Both are registered on a DLT platform first; here they are recorded, so that an SMS send can be matched to them. Recording them here does not register them with DLT. The SMS account response's keepsRegistry and available describe the configured registry permission and availability, not a promise of delivery.
Only approved registry templates are listed; inactive approved templates can still appear. A send also requires an active template and the other send guards described in Messages.
| Method | Path | What it does |
|---|---|---|
GET | /external/v1/sms/account | The account's limits, what it has sent this month, and the message types it may send |
GET | /external/v1/sms/senders | The account's own headers, [{"senderId": …, "isDefault": …}] |
PUT | /external/v1/sms/senders/{senderId} | Adds a header, six letters or six digits, with {"isDefault": true} to make it the default |
DELETE | /external/v1/sms/senders/{senderId} | Deletes a header no template uses: 204 |
GET | /external/v1/sms/templates | The account's templates, then those its parent shares with it |
POST | /external/v1/sms/templates | Adds a template: 201 |
PUT | /external/v1/sms/templates/{id} | Changes a template, given in full |
DELETE | /external/v1/sms/templates/{id} | Deletes a template: 204 |
PUT | /external/v1/sms/templates/{id}/sharing | Lets none, all, or the named sub-accounts send it |
- Name
templateId- Type
- string
- Description
Required: the template's DLT id, up to 32 digits.
- Name
senderId- Type
- string
- Description
Required: one of the account's headers. A promotional template goes under a six-digit header, and the others under a six-letter one.
- Name
name- Type
- string
- Description
Required: a name of your own, at most 80 characters.
- Name
body- Type
- string
- Description
Required: the text as registered on DLT, at most 2,000 characters, with each variable as
{#var#}, at most 30 of them.
- Name
variableKeys- Type
- string[]
- Description
A name for each variable, in order, such as
["otp", "minutes"]. Omitted or empty: positional names1tonare used. When supplied, keys use unique ASCII letters, digits or_, 1 to 30 characters each; their number must match the variable count.
- Name
type- Type
- string
- Description
Required: the DLT type,
transactional,service_implicit,service_explicitorpromotional.
- Name
unicode- Type
- boolean
- Description
Whether the text is Unicode;
falseby default.
- Name
active- Type
- boolean
- Description
Whether it may be sent;
trueby default.
Add a template
curl -X POST https://api.oblic.app/external/v1/sms/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"templateId": "1107161234567890123",
"senderId": "EXMPLE",
"name": "Sign-in code",
"body": "Your Example code is {#var#}. It is valid for {#var#} minutes.",
"variableKeys": ["code", "minutes"],
"type": "service_implicit"
}'
- Only the accounts Oblic registers SMS for add and change headers and templates; any other account is refused,
403 REGISTRY_NOT_ALLOWED, and sends the templates shared with it. - Sharing takes
{"scope": "none" | "all" | "selected", "accounts": […]}, at most 1,000 sub-accountexternalIds forselected. Each named account must belong to the parent. An empty selected list shares with no sub-account. - A header's default flag is set by each
PUT: one without"isDefault": truemakes the header not the default. Making one default unsets the account's previous default.
| Refused | cd | When |
|---|---|---|
| 400 | INVALID_TEMPLATE | The header doesn't fit the type, there are more than 30 variables, or variableKeys doesn't name each once |
| 403 | REGISTRY_NOT_ALLOWED | The account doesn't register SMS of its own |
| 404 | TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND | No such template, header or sub-account |
| 409 | TEMPLATE_EXISTS | A template with that DLT id is registered already |
| 409 | SENDER_IN_USE | Deleting a header that templates use |
| 422 | SENDER_NOT_ALLOWED | The header is not one of the account's |
| 422 | MESSAGE_TYPE_NOT_ENABLED | The template's type is not one Oblic sends: the account's messageTypes, by default service_implicit only |
WhatsApp number and templates
A WhatsApp message goes from the account's connected WhatsApp Business number, by a template Meta has approved.
| Method | Path | What it does |
|---|---|---|
POST | /external/v1/whatsapp/connection | Connects the number, or replaces the one connected |
GET | /external/v1/whatsapp/connection | The connected number: 404 WHATSAPP_NOT_CONNECTED without one |
DELETE | /external/v1/whatsapp/connection | Disconnects it: 204 |
GET | /external/v1/whatsapp/templates | The templates, with Meta's review of each |
POST | /external/v1/whatsapp/templates | Submits a template to Meta for review: 201 |
GET | /external/v1/whatsapp/recipients/{number} | What the account may send a number now |
Connecting takes the result of Embedded Signup run with Oblic's Meta app: code, phoneNumberId, wabaId, optionally businessId, and the six-digit pin the number is registered with. The answer's status is INTEGRATED once every connection step is confirmed; a connection that stopped part-way stays PENDING. Retry with valid signup inputs; a spent or expired code is not guaranteed to work again. Meta refusing a step is 502, naming it, such as WHATSAPP_REGISTER_REFUSED, without returning its raw response body.
- Name
name- Type
- string
- Description
Required: lowercase ASCII letters, digits and
_, such asorder_shipped. Oblic's expanded account-and-language-qualified name must be at most 100 characters; a name that exceeds that bound is refused before Meta is called. Use the returnednamewhen sending, rather than assuming the short input is Meta's stored name.
- Name
language- Type
- string
- Description
The template's language: two lowercase ASCII letters, optionally
_and two uppercase ASCII letters, such asen,hioren_US;enwhen omitted. One name can have a template in each language; repeating the same name and language is a conflict.
- Name
category- Type
- string
- Description
Required:
MARKETING,UTILITYorAUTHENTICATION.
- Name
components- Type
- object[]
- Description
Required: the template's header, body, footer and buttons, in Meta's shape, with examples of their variables.
Submit a template
curl -X POST https://api.oblic.app/external/v1/whatsapp/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "order_shipped",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} has shipped.",
"example": { "body_text": [["Asha", "1042"]] }
}
]
}'
- A template's
statusis the stored review status from Meta, for examplePENDING,APPROVEDorREJECTED;rejectionReasonmay be absent.201means submitted, not approved. OnlyAPPROVEDtemplates are sendable. No review-completion deadline is promised. - A recipient answers
number,optedOutand when and how (optedOutAt,optOutSource),lastInboundAt, andsessionOpenUntil: the 24-hour window measured from the person's last inbound message.optedOutconcerns marketing, not every message. With no inbound history,lastInboundAtandsessionOpenUntilarenull. A session timestamp alone does not guarantee that a send is accepted: the other send guards still apply.
| Refused | cd | When |
|---|---|---|
| 409 | TEMPLATE_EXISTS | The account has a template of that name in that language |
| 422 | WHATSAPP_NOT_CONNECTED | Submitting a template without a connected number |
| 422 | TEMPLATE_NAME_TOO_LONG | The name is too long for Meta |
| 422 | TEMPLATE_REFUSED | Meta refused the template; a generic localized refusal, not Meta's raw response text |
| 422 | INVALID_NUMBER | A recipient's number is not in international format |
| 502 | WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSED | Meta refused a step of connecting the number |
| 503 | WHATSAPP_UNAVAILABLE | Meta could not be reached during a connection step |