---
title: "Send templates"
description: "Send a saved template, such as a verification code, with your own values."
url: "https://docs.goomzo.africa/docs/developers/messages/templates"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Messages"
related:
  - /docs/developers/messages
  - /docs/developers/messages/send
  - /docs/developers/messages/broadcasts
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Send templates

> Send a saved template, such as a verification code, with your own values.

Your system sends a saved [template](https://docs.goomzo.africa/docs/developers/templates?utm_source=llms&utm_medium=ai) by its name, with the values it needs. Goomzo fills
in the customer's details and your values, and sends it on the template's channel.

## Requirements

- An API key with the `messages.send` permission.
- A saved template. See [Create templates](https://docs.goomzo.africa/docs/developers/templates/create?utm_source=llms&utm_medium=ai).

## Values in a template

| Placeholder        | Filled with                                                                   |
| ------------------ | ----------------------------------------------------------------------------- |
| `{{name}}`         | The customer's name.                                                          |
| `{{attributes.x}}` | One of the customer's details, such as `{{attributes.plan}}`.                 |
| `{{data.x}}`       | A value your system sends.                                                    |
| `{{secret.x}}`     | A value your system sends, delivered as it is but kept and shown as `••••••`. |

Any of them can have a fallback after `|`, such as `{{name|there}}`.

## Requests

```text
POST /v1/messages
```

### Request syntax

```json
{
  "messages": [{ "to": "<PHONE_NUMBER>", "template": "<TEMPLATE_NAME>", "variables": { "<KEY>": "<VALUE>" } }]
}
```

| Placeholder        | Description                                                                      | Sample value                            |
| ------------------ | -------------------------------------------------------------------------------- | --------------------------------------- |
| `<PHONE_NUMBER>`   | _String._ Who it's to, with the country code. Or use `customerId`.               | `+255712345678`                         |
| `<TEMPLATE_NAME>`  | _String._ The template's name, ignoring case, or its id.                         | `auth_1`                                |
| `<KEY>`, `<VALUE>` | _Object of strings._ A value for each `{{data.x}}` and `{{secret.x}}`. Up to 50. | `{ "code": "482913", "minutes": "10" }` |

### Example request

For a template `auth_1` that reads `Hi {{name|there}}, your code is {{secret.code}}. It expires in {{data.minutes}} minutes.`:

```bash
curl https://api.goomzo.africa/v1/messages \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-7f3a" \
  -d '{ "messages": [{ "to": "+255712345678", "template": "auth_1",
        "variables": { "code": "482913", "minutes": "10" } }] }'
```

With the SDK:

```ts
await goomzo.messages.sendOne({ to: '+255712345678', template: 'auth_1', variables: { code: '482913', minutes: '10' } })
```

## Responses

The customer reads "Hi Amina, your code is 482913. It expires in 10 minutes." The answer shows what Goomzo keeps:

```json
{
  "items": [
    {
      "id": "msg_7c1x9v2b4n6m8q0w",
      "channel": "sms",
      "content": { "text": "Hi Amina, your code is ••••••. It expires in 10 minutes." },
      "status": "sending",
      "private": true
    }
  ]
}
```

**Important:** Goomzo never shows a secret again, in the dashboard, the API or webhooks. It's kept sealed only until
the message is sent, then removed.

## Notes

- **Channel:** the template's own. `channel` can be left out.
- **Every value, and only those:** a missing value, or one the template doesn't use, is an error that names it,
  such as `variables.code`, so a typo shows at once.
- **Retries:** send an `Idempotency-Key`, so a retry never sends a code twice. See [Safe retries](https://docs.goomzo.africa/docs/developers/idempotency?utm_source=llms&utm_medium=ai).
- **Only through the API:** a template with `{{data.x}}` or `{{secret.x}}` isn't offered in Compose or broadcasts.
- **A ready request:** each template in Goomzo shows one under **Send from your system**.

## Next steps

- [Authentication templates](https://docs.goomzo.africa/docs/developers/templates/authentication?utm_source=llms&utm_medium=ai): verification codes on WhatsApp.
- [Create templates](https://docs.goomzo.africa/docs/developers/templates/create?utm_source=llms&utm_medium=ai)

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)