# List SMS templates

`GET /v1/sms/templates`

Returns SMS templates as a cursor-paginated list. The workspace's templates
come first, newest first, followed by our built-in templates by default.
Set `order=asc` to reverse this order.

Filter by scope, category, status, or language. Use `q` for a
case-insensitive substring match against slug, name, and description. The
response is shallow; read a version to retrieve its content and variables.

## Code samples

**TypeScript**

```ts
for await (const tpl of bird.smsTemplates.list({ scope: "system" })) {
  console.log(tpl.id, tpl.slug);
}
```

Examples: [TypeScript](/docs/api/reference/list-sms-templates.ts.md) · [Python](/docs/api/reference/list-sms-templates.py.md) · [Go](/docs/api/reference/list-sms-templates.go.md) · [PHP](/docs/api/reference/list-sms-templates.php.md) · [CLI](/docs/api/reference/list-sms-templates.cli.md) · [MCP](/docs/api/reference/list-sms-templates.mcp.md) · [cURL](/docs/api/reference/list-sms-templates.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "smt_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "slug": "welcome-email",
      "scope": "system",
      "status": "active",
      "category": "transactional",
      "draft_version_id": "smv_01krdgeqcxet5s7t44vh8rt9mg",
      "live_version_id": "smv_01krdgeqcxet5s7t44vh8rt9mg",
      "published_version_id": "smv_01krdgeqcxet5s7t44vh8rt9mg",
      "default_language": "pt-BR",
      "available_languages": [
        "pt-BR"
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `scope` (string)

  Filter by who owns the template. Use `system` for built-in templates and `workspace` for templates your workspace created.

  Possible values: `system`, `workspace`
- `category` (string)

  Return templates in this category.

  Possible values: `transactional`, `marketing`, `authentication`
- `status` (string)

  Return templates with this lifecycle status.

  Possible values: `draft`, `pending`, `active`, `rejected`, `inactive`
- `language` (string): Return templates whose published content contains this language, after the tag is canonicalized. Draft-only languages do not match.
- `q` (string): A case-insensitive substring search across slug, name, and description.
- `sort` (string)

  Field to sort by.

  Possible values: `created_at`
- `order` (string)

  Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

  Possible values: `asc`, `desc`
- `limit` (integer): Maximum number of items to return per page.
- `starting_after` (string): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

## Response body

- `data` (array of object, required): One page of SMS templates.
- `data.id` (string, required): Template ID.
- `data.workspace_id` (nullable string, required): The workspace that owns the template. Null for a built-in `system` template.
- `data.slug` (string, required): The immutable handle used to address and send the template.
- `data.name` (string, required): The template's display name.
- `data.description` (nullable string, required): What the template is for. Null if it has no description.
- `data.scope` (string, required)

  Whether the template is one of our built-in templates (`system`) or one your workspace created (`workspace`).

  Possible values: `system`, `workspace`
- `data.status` (string, required)

  Where the template stands as a whole. The same five states on every channel.

  - `draft`: nothing has ever gone live.
  - `pending`: nothing is live and at least one language is in review.
  - `active`: at least one language is live, so something can be sent.
  - `rejected`: it was reviewed and every language was refused.
  - `inactive`: nothing is live and nothing is in review, so content was withdrawn or was blocked before anything went live.

  A template with one language live is `active` even while another is still
  drafted or refused. Read `languages` for the state of each language and its
  reason.

  Which values a channel reports follows its review model. A channel whose
  content a third party reviews uses all five. On email and SMS, where content
  goes live on publish, a template is `draft`, `active` or `inactive`, and
  `pending` and `rejected` are reserved for the review stage coming to both, so
  a template reaching either is not a breaking change.

  Possible values: `draft`, `pending`, `active`, `rejected`, `inactive`
- `data.category` (string, required)

  Why messages use this template. Use `authentication` for one-time codes, `marketing` for promotions, and `transactional` for service messages.

  Possible values: `transactional`, `marketing`, `authentication`
- `data.draft_version_id` (nullable string, required): The permanent editable draft version. Null for a built-in template.
- `data.live_version_id` (nullable string, required): The version sends resolve to, or null before first publication.
- `data.published_version_id` (nullable string, required): Deprecated. Use `live_version_id`, which carries the same value.
- `data.languages` (object, required): Each language and its live or draft state, keyed by canonical BCP-47 tag.
- `data.default_language` (string, required): The draft's default language.
- `data.available_languages` (array of string, required): Languages the live version can currently send. Empty before first publication.
- `data.last_submitted_at` (nullable string, required): When the template was last published. Null before first publication and for built-in templates.
- `data.created_at` (nullable string, required): When the template was created. Null for built-in templates.
- `data.updated_at` (nullable string, required): When the template was last modified. Null for built-in templates.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Related resources

- [Sending an SMS with a template](/learn/sms/sending-an-sms-with-a-template) (video)
- [Preview message segments](/tools/sms-segment-calculator) (tool)
- [SMS content and templates](/sms-api/features/marketing/templates) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms-templates)