Templates

A template stores the content of an email (HTML, text, subject, sender) with {{{VARIABLE}}} placeholders. Your code then sends the template by ID or alias and passes the variable values. Templates are managed through the API.

#Create a template

curl -X POST https://api.usend.et/templates \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "alias": "welcome",
    "from": "Acme <[email protected]>",
    "subject": "Welcome, {{{NAME}}}",
    "html": "<p>Hi {{{NAME}}}, you have {{{CREDITS}}} free credits.</p>",
    "text": "Hi {{{NAME}}}, you have {{{CREDITS}}} free credits.",
    "variables": [
      { "key": "NAME", "type": "string", "fallback_value": "there" },
      { "key": "CREDITS", "type": "number" }
    ]
  }'

{ "object": "template", "id": "f3b9756c-f4f4-44da-bc00-9f7903c8a83f" }

name and html are required. alias is an optional, human-friendly ID: lowercase letters, digits, - and _, up to 64 characters, unique in your organization. Anywhere the API takes a template ID, you can pass the alias instead.

#Variables

Placeholders use three braces: {{{NAME}}}. Every placeholder must be declared in variables:

A template can declare up to 50 variables. FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL, CONTACT and THIS are reserved and cannot be declared.

In html, values are HTML-escaped. In subject and text, they are inserted as is.

#Draft and publish

Creating or editing a template changes its draft. Sends always use the last published version, so you can edit safely without affecting live email.

curl -X POST https://api.usend.et/templates/welcome/publish \
  -H "Authorization: Bearer us_123456789"

Publishing fails with 422 if the template has no HTML or uses a placeholder that is not declared in variables. This catches typos like {{{NAEM}}} before they reach an inbox.

GET /templates/{id} returns status (draft or published), published_at, and has_unpublished_versions, which is true when the draft differs from the published version.

#Send with a template

Pass template instead of html and text to POST /emails:

curl -X POST https://api.usend.et/emails \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "template": {
      "id": "welcome",
      "variables": { "NAME": "Ann", "CREDITS": 50 }
    }
  }'

How the email is built:

• html and text come from the published template. Sending html or text together with template fails with 422.
• from, subject and reply_to come from the template unless you send them. Your values win. If neither the request nor the template has a from, the request fails.
• A variable you don't pass uses its fallback_value. A placeholder with neither a value nor a fallback fails the request with 422.
• Passing a variable the template does not declare fails with 422.
• A template that was never published cannot be sent.

Templates work in batch requests too.

#Manage templates

See the Templates API reference.