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.


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.

MethodPathWhat it does
GET/external/v1/templatesThe templates, newest first, without their HTML
GET/external/v1/templates/{id}One template, with its HTML and the variables it takes
POST/external/v1/templatesMakes 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. variables lists the ones the subject and HTML hold, ignoring case, in first-appearance order and spelling.
  • kind is html for a template made through the API, and designed for 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 @unsubscribe or @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 cursor and limit: 25 per page by default, from 1 to 100, as Pagination describes. Treat the returned cursor as opaque.
RefusedcdWhen
400TEMPLATE_TOO_LARGEThe HTML is over 65,535 bytes
404TEMPLATE_NOT_FOUNDThe account has no template with that id
409TEMPLATE_DESIGNEDReplacing 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.

MethodPathWhat it does
GET/external/v1/sms/accountThe account's limits, what it has sent this month, and the message types it may send
GET/external/v1/sms/sendersThe 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/templatesThe account's templates, then those its parent shares with it
POST/external/v1/sms/templatesAdds 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}/sharingLets 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 names 1 to n are 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_explicit or promotional.

  • Name
    unicode
    Type
    boolean
    Description

    Whether the text is Unicode; false by default.

  • Name
    active
    Type
    boolean
    Description

    Whether it may be sent; true by 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-account externalIds for selected. 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": true makes the header not the default. Making one default unsets the account's previous default.
RefusedcdWhen
400INVALID_TEMPLATEThe header doesn't fit the type, there are more than 30 variables, or variableKeys doesn't name each once
403REGISTRY_NOT_ALLOWEDThe account doesn't register SMS of its own
404TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUNDNo such template, header or sub-account
409TEMPLATE_EXISTSA template with that DLT id is registered already
409SENDER_IN_USEDeleting a header that templates use
422SENDER_NOT_ALLOWEDThe header is not one of the account's
422MESSAGE_TYPE_NOT_ENABLEDThe 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.

MethodPathWhat it does
POST/external/v1/whatsapp/connectionConnects the number, or replaces the one connected
GET/external/v1/whatsapp/connectionThe connected number: 404 WHATSAPP_NOT_CONNECTED without one
DELETE/external/v1/whatsapp/connectionDisconnects it: 204
GET/external/v1/whatsapp/templatesThe templates, with Meta's review of each
POST/external/v1/whatsapp/templatesSubmits 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 as order_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 returned name when 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 as en, hi or en_US; en when 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, UTILITY or AUTHENTICATION.

  • 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 status is the stored review status from Meta, for example PENDING, APPROVED or REJECTED; rejectionReason may be absent. 201 means submitted, not approved. Only APPROVED templates are sendable. No review-completion deadline is promised.
  • A recipient answers number, optedOut and when and how (optedOutAt, optOutSource), lastInboundAt, and sessionOpenUntil: the 24-hour window measured from the person's last inbound message. optedOut concerns marketing, not every message. With no inbound history, lastInboundAt and sessionOpenUntil are null. A session timestamp alone does not guarantee that a send is accepted: the other send guards still apply.
RefusedcdWhen
409TEMPLATE_EXISTSThe account has a template of that name in that language
422WHATSAPP_NOT_CONNECTEDSubmitting a template without a connected number
422TEMPLATE_NAME_TOO_LONGThe name is too long for Meta
422TEMPLATE_REFUSEDMeta refused the template; a generic localized refusal, not Meta's raw response text
422INVALID_NUMBERA recipient's number is not in international format
502WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSEDMeta refused a step of connecting the number
503WHATSAPP_UNAVAILABLEMeta could not be reached during a connection step
Was this page helpful?