---
title: "List Apple Messages templates"
canonical: "https://bird.com/docs/api/reference/list-amb-templates"
---

# List Apple Messages templates

`GET /v1/amb/templates`

Returns Apple Messages 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, content kind, 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.amb.templates.list({ scope: "system" })) {
  console.log(tpl.id, tpl.slug);
}
```

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

## Example response `200`

```json
{
  "data": [
    {
      "id": "amt_01krdgeqcxet5s7t44vh8rt9mg",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "slug": "welcome-email",
      "scope": "system",
      "status": "active",
      "category": "transactional",
      "content_kind": "text",
      "draft_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
      "live_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
      "published_version_id": "amv_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`
- `status` (string)

  Return templates with this lifecycle status.

  Possible values: `draft`, `pending`, `active`, `rejected`, `inactive`
- `content_kind` (string)

  Return templates whose live or draft content is this kind.

  Possible values: `text`, `attachment`, `rich_link`, `quick_reply`, `list_picker`, `time_picker`, `form`, `apple_pay`, `authenticate`, `imessage_app`, `interactive`
- `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 Apple Messages 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, fixed at creation. On Apple Messages the category describes intent and becomes the message's reporting `category`; it grants and restricts nothing. Use `marketing` for promotions and `transactional` for service messages.

  Possible values: `transactional`, `marketing`
- `data.content_kind` (string, required)

  Derived message classification, matching the default language's content.

  Possible values: `text`, `attachment`, `rich_link`, `quick_reply`, `list_picker`, `time_picker`, `form`, `apple_pay`, `authenticate`, `imessage_app`, `interactive`
- `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

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)