--- title: "List email templates" method: GET path: "/v1/email/templates" tags: ["email-templates"] --- # List email templates `GET /v1/email/templates` ## Request - Base URL: `https://us1.platform.bird.com` - URL: `https://us1.platform.bird.com/v1/email/templates` - Auth: one of: - HTTP bearer - API key in cookie `bird_session` Returns a paginated list of email templates, newest first. The list covers both the workspace's own templates and our built-in `system` templates. Use `scope` to get only one of the two, or leave it out to get both. When you leave it out, the workspace's own templates come first, newest first, and our built-in templates fill the rest of the list once the workspace's templates run out. Filter further by category or authoring format, or search with `q`, a case-insensitive substring match against the template's slug, name, and description. Our built-in templates come in five visual themes. Each theme ships its own set of eight emails, and the sets overlap only partly. Use `theme` to see one of them. A template your workspace authored has no theme, so naming one returns our built-ins alone. ## Query parameters - `scope` 'system' | 'workspace': Whether the template is one of our built-in templates (`system`) or one your workspace created (`workspace`). - `category` 'transactional' | 'marketing': Whether the template is for `transactional` email or `marketing` email. - `source` string: The authoring format the template is written in, fixed at creation. `html` is finished markup you provide, optionally personalized with Liquid. - `theme` 'arcane' | 'barebone' | 'matte' | 'protocol' | 'studio': Filter by the visual theme a built-in template is designed in. Only built-in `system` templates have a theme, so naming one returns built-ins alone. - `q` string - `limit` integer - `starting_after` string - `ending_before` string ## Headers - `X-Workspace-Id` string - `X-Organization-Id` string ## Response `200` Paginated list of email templates. - EmailTemplateList - `data` EmailTemplateSummary[], required: Page of email templates. - `id` string, required - `workspace_id` string, required - `slug` string, required: A template's slug: what you send it by, for example `welcome-email`. Email and SMS slugs stay fixed after creation. WhatsApp slugs can change only before the first submission. A slug can contain lowercase letters, numbers, hyphens, and underscores, has to start and end with a letter or a number, and can be up to 63 characters long. - `name` string, required: The template's display name, shown wherever the template is listed. You can change it any time. It defaults to the slug if you do not set one. - `description` string, nullable, required: What the template is for, in your own words. Null if you have not set one. - `scope` 'system' | 'workspace', required: Whether the template is one of our built-in templates (`system`) or one your workspace created (`workspace`). - `status` 'draft' | 'pending' | 'active' | 'rejected' | 'inactive', 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. - `category` 'transactional' | 'marketing', required: Whether the template is for `transactional` email or `marketing` email. - `source` string, required: The authoring format the template is written in, fixed at creation. `html` is finished markup you provide, optionally personalized with Liquid. - `theme` string, required: The visual theme a built-in template is designed in. Each of the catalog's five themes ships its own set of eight emails, and the sets overlap only partly, so the theme is what you choose between once you know which email you want. Only our built-in `system` templates have one. - `draft_version_id` string, required - `live_version_id` string, required - `published_version_id` string, required - `live_version_number` integer, nullable, required: The live version's sequential number (1, 2, 3…), the same one version history reports, or null if the template has never been published. A built-in `system` template is permanently published as version 1. A rollback moves it backwards, because it names the version that is live rather than how many exist. - `available_languages` LanguageTag[], required: The languages this template currently supports for sending, as BCP-47 tags. Empty until the template is published, because sends serve published content. This set may shrink for reasons other than editing, so read it rather than assuming it matches what was published. - `default_language` string, required: A language tag in BCP-47 form, for example `en` or `pt-BR`. - `languages` object, required: Every language this template has, keyed by language tag, each with its state. Enough to show which templates need attention in a list without a request per row. - `last_submitted_at` string, date-time, nullable, required: When this template was last submitted. Null if it never has been. Only submitting moves this timestamp, so a rollback keeps reporting the last real submit. - `created_at` string, date-time, nullable, required: When the template was created. Null for a built-in `system` template. - `updated_at` string, date-time, nullable, required: When the template was last modified. Null for a built-in `system` template. - `next_cursor` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists. - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists. - `refresh_cursor` string, nullable, 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`. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)