> ## Documentation Index > Fetch the complete documentation index at: https://docs.prelude.so/llms.txt > Use this file to discover all available pages before exploring further. # Create a message template > Create a message template. It always lands in `draft`: nothing is sent with it and no registration is opened until you submit it for review. In order to get access to this endpoint, contact our support team. Create a message template. Only `name` is required, and the template always lands in `draft`: nothing is sent with it and no registration is opened until you [submit it for review](/notify/v2/api-reference/management/templates/submit-template). The `variables` of the template are read from the `{{placeholder}}` names in your variants, so you never set them yourself. The same goes for `status` and `region_statuses`, which follow the review and the per-country registrations. While the template is a draft, every country in `region_statuses` reads `draft`. ## WhatsApp When `channels` include `whatsapp`, set `variable_examples` with one sample value per variable: WhatsApp needs them to review the template. Once we approve the template, every variant is sent to your WhatsApp Business Account for review, and the `whatsapp` object of each variant shows how far it is. A `transactional` template is submitted to WhatsApp as `utility`. WhatsApp can approve it as `marketing` instead when it finds promotional content in it, which changes its price. The `whatsapp.category` of each variant shows the category WhatsApp holds. ## OpenAPI ````yaml post /v2/notify/management/templates openapi: 3.1.0 info: title: Prelude API version: 2.0.0 description: The Prelude API allows you to send messages to your users. contact: email: support@prelude.so servers: - url: https://api.prelude.dev description: Production server security: - apiToken: [] tags: - name: Notify description: Send transactional and marketing messages with compliance enforcement. - name: Transactional description: Send transactional messages (deprecated - use Notify API instead). - name: Verify description: Verify phone numbers. - name: Watch description: Evaluate email addresses and phone numbers for trustworthiness. - name: Lookup description: >- Retrieve detailed information about a phone number including carrier data, line type, and portability status. paths: /v2/notify/management/templates: post: tags: - Notify summary: Create a message template description: > Create a message template. It always lands in `draft`: nothing is sent with it and no registration is opened until you submit it for review. In order to get access to this endpoint, contact our support team. operationId: createNotifyTemplate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateNotifyTemplateRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/NotifyTemplate' '400': description: KO content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateNotifyTemplateRequest: type: object required: - name properties: name: type: string description: The name of the template. examples: - Acme Receipts type: type: string description: What the template is used for. Defaults to `transactional`. enum: - transactional - marketing channels: type: array description: The channels the template should be delivered over. items: type: string enum: - sms - rcs - whatsapp - viber - zalo - telegram variants: type: array description: The wording of the message, one entry per locale. items: $ref: '#/components/schemas/NotifyTemplateVariant' default_locale: type: string description: >- The locale used when the recipient's own locale has no variant. Defaults to `en`. examples: - en countries: type: array description: The countries the template should work in. items: $ref: '#/components/schemas/NotifyTemplateCountry' variable_examples: type: object description: > One sample value per `{{variable}}` of the variants. WhatsApp requires a sample for every variable to review the template, so set them on a template whose `channels` include `whatsapp`. Every key must be a variable used in the variants. additionalProperties: type: string examples: - name: Ana order_id: A-1042 NotifyTemplate: type: object required: - id - type - name - status - channels - variables - variants - default_locale - countries - region_statuses - created_at properties: id: type: string description: >- The identifier of the template, to pass as `template_id` when sending a message. examples: - template_01k8ap1btqf5r9fq2c8ax5fhc9 type: type: string description: | What the template is used for. Possible values are: * `transactional` - A message triggered by an action of the recipient. * `marketing` - A promotional message, subject to marketing rules. enum: - transactional - marketing name: type: string description: The name of the template. examples: - Acme Receipts status: type: string description: | Where the template stands in the approval flow. Possible values are: * `draft` - Yours to edit. Nothing is sent with it yet. * `pending` - Submitted, and waiting on our review and on the per-country registrations. * `ready` - Approved and usable in every country you asked for. * `rejected` - Refused. Contact support for the reason. enum: - draft - pending - ready - rejected channels: type: array description: The channels the template can be delivered over. items: type: string enum: - sms - rcs - whatsapp - viber - zalo - telegram variables: type: array description: >- The placeholder names found in the variants, to fill in when sending. items: type: string examples: - - name - order_id variants: type: array description: The wording of the message, one entry per locale. items: $ref: '#/components/schemas/NotifyTemplateVariantWithStatus' default_locale: type: string description: The locale used when the recipient's own locale has no variant. examples: - en countries: type: array description: >- The countries the template works in, with the monthly volume recorded for each. items: $ref: '#/components/schemas/NotifyTemplateCountry' region_statuses: type: object description: >- The readiness of the template per country, keyed by ISO 3166-1 alpha-2 country code. additionalProperties: $ref: '#/components/schemas/NotifyTemplateRegionStatus' created_at: type: string format: date-time description: The date and time when the template was created. examples: - '2024-01-01T12:00:00Z' Error: type: object properties: code: type: string description: The error code. examples: - invalid_phone_number message: type: string examples: - >- The provided phone number is invalid. Provide a valid E.164 phone number. description: A human-readable message describing the error. type: type: string examples: - bad_request description: The error type. request_id: type: string examples: - 3d19215e-2991-4a05-a41a-527314e6ff6a description: >- A string that identifies this specific request. Report it back to us to help us diagnose your issues. param: type: string examples: - phone_number description: The parameter the error refers to, when it applies to a single one. required: - code - message - type NotifyTemplateVariant: type: object required: - locale - text properties: locale: type: string description: The BCP-47 locale this wording is written in. examples: - en text: type: string description: >- The message body, with `{{variable}}` placeholders for the values you pass when sending. examples: - Hi {{name}}, your order {{order_id}} shipped. NotifyTemplateCountry: type: object required: - country properties: country: type: string description: An ISO 3166-1 alpha-2 country code the template should work in. examples: - ES monthly_volume: type: integer description: >- The number of messages you expect to send to this country each month. Required, and at least 1000, for a country that needs a sender registration. examples: - 5000 NotifyTemplateVariantWithStatus: allOf: - $ref: '#/components/schemas/NotifyTemplateVariant' - type: object properties: whatsapp: $ref: '#/components/schemas/NotifyTemplateWhatsAppStatus' NotifyTemplateRegionStatus: type: object required: - status - requires_registration properties: status: type: string description: > How far this country is from being usable with the template. Possible values are: * `draft` - The template is still a draft, so nothing is sent with it in this country yet. * `pending` - Registration is needed in this country and is not ready yet. * `in_review` - The template was submitted and is being reviewed, along with the registration this country needs. * `ready` - The template can be used in this country. * `rejected` - The template was refused. Contact support for the reason. enum: - draft - pending - in_review - ready - rejected requires_registration: type: boolean description: >- Whether this country needs a sender registration before the template can be used there. examples: - true NotifyTemplateWhatsAppStatus: type: object description: > Where this language stands on WhatsApp. Present only on a template whose `channels` include `whatsapp`. Once we approve the template, each language is sent to WhatsApp for review. WhatsApp reviews every language on its own, usually within minutes and sometimes up to a few days. required: - status properties: status: type: string description: | Possible values are: * `not_submitted` - Not sent to WhatsApp yet. A template is sent once we approve it. * `pending` - WhatsApp is reviewing this language. * `approved` - WhatsApp approved this language. Messages can be sent with it. * `rejected` - WhatsApp rejected this language. See `rejection_reason`. Fix the `text` of this variant with an update, and it is sent back for review. * `paused` - WhatsApp paused this language after poor recipient feedback. * `disabled` - WhatsApp no longer sends this language. * `sync_failed` - The language could not be sent to WhatsApp. See `error`. enum: - not_submitted - pending - approved - rejected - paused - disabled - sync_failed category: type: string description: > The category WhatsApp holds for this language, which sets its price. A `transactional` template is submitted as `utility`, but WhatsApp approves it as `marketing` when it finds promotional content in it. enum: - utility - marketing - authentication rejection_reason: type: string description: >- WhatsApp's reason for a rejection, such as `invalid_format`, `incorrect_category`, `promotional` or `abusive_content`. Set only with the `rejected` status. examples: - invalid_format rejection_detail: type: string description: >- WhatsApp's explanation of the rejection. WhatsApp sends one for `invalid_format` only. examples: - >- Your template has parameters placed next to each other (like {{1}}{{2}}) without text or punctuation between them. rejection_recommendation: type: string description: >- WhatsApp's advice to fix the rejection. WhatsApp sends one for `invalid_format` only. examples: - >- Separate parameters with descriptive text and ensure each parameter is clearly contextualized. error: type: string description: >- Why the language could not be sent to WhatsApp. Set only with the `sync_failed` status. securitySchemes: apiToken: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.