> ## Documentation Index > Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt > Use this file to discover all available pages before exploring further. # Create and manage email templates > Create, update, and delete custom email templates for invoice notifications and other Tesouro email types using the API. The `/mail-templates*` endpoints require a [app access token](/finops/guides/authentication/client-credentials). ## Create an email template To create a custom [email template](/finops/guides/advanced/email-templates/index), call [`POST /mail-templates`](/finops/reference/openapi/mail-templates/post-mail-templates) endpoint. The `type` field in the request body represents one of Tesouro's customizable email templates. For the complete list of template types, see [Template types](/finops/guides/advanced/email-templates/index#types). You can create a default template for a template type by setting the value of the `is_default` field to `true`. If the `is_default` field is left unspecified, its value is set to `false`. The following request creates a new default template for English invoice emails: ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/mail-templates' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "language": "en", "subject_template": "New invoice from {{entity_name}}!", "body_template": " \n \n \n \n

\n\n", "name": "New invoice template", "type": "receivables_invoice", "is_default": true }' ``` The `subject_template` and `body_template` fields can include variables related to the template type. To view the list of available variables for each template type, see the [Retrieving variables](/finops/guides/advanced/variables#list). Variables for custom templates should be enclosed in curly braces, as shown: `{{YOUR_VARIABLES}}`. The successful response the ID created of the created template and other details of the template. ```json lines theme={null} { "id": "5b031d0c-dcb6-4aa0-b660-44df31ebf0db", "type": "receivables_invoice", "name": "New invoice template", "is_default": true, "language": "en", "subject_template": "New invoice from {{entity_name}}!", "body_template": " \n \n \n \n

\n\n", "created_at": "2023-12-01T16:04:59.177241+00:00", "updated_at": "2023-12-01T16:04:59.177255+00:00" } ``` **Default templates** You can only have one default template per `language` and `type` combination. Therefore, creating a new default template will overwrite any existing default template for that language and template type. ## Retrieve a template To get information about a specific custom template, call [`GET /mail-templates/{template_id}`](/finops/reference/openapi/mail-templates/get-mail-templates-id) endpoint: ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/mail-templates/44df31ebf0db...5b031d0c' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` A successful response returns information about the custom template with the specified ID: ```json lines theme={null} { "id": "44df31ebf0db-dcb6-4aa0-b660-5b031d0c", "type": "receivables_quote", "name": "New quote template", "is_default": false, "language": "en", "subject_template": "New invoice from {{entity_name}}!", "body_template": " \n \n \n \n

\n\n", "created_at": "2023-12-11T16:04:59.177241+00:00", "updated_at": "2023-12-12T19:54:59.177255+00:00" } ``` ## Set template as default You can set a custom template as default when creating custom templates by specifying the `is_default` field to `true` in the request object. You can also mark a template as default by calling [`POST /mail-templates/{template_id}/make-default`](/finops/reference/openapi/mail-templates/post-mail-templates-id-make-default): ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/mail-templates/44df31ebf0db...5b031d0c/make-default' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` The successful response sets the template as default for the `type` and `language`. To make a template of the same `type` the default for another language, you must send another `POST` request to the `/mail-templates/{template_id}/make-default` endpoint with template UUID. ## Preview mail templates You can preview the current default mail template for all template types. The preview endpoint returns the default template for the template type and language requested. This can be either Tesouro's system template or your custom template. To preview a mail template, call `POST /mail-templates/preview`: ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/mail-templates/preview' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "body": "Find attached the current rates for the items requested", "document_type": "receivables_quote", "language_code": "en", "subject": "Your new quote is here" }' ``` * The `body` and `subject` fields in the request object represent the text to replace the `subject_text` and `body_template` variables in the mail template. * If the `subject_text` and `body_template` variables are not used in the template, any text provided in the `body` and `subject` fields will be voided. You can provide an empty string if these variables are not used in the template. The successful request returns a preview of the email body and subject for the current default mail template in the response. ## Get all templates To retrieve all templates, call [`GET /mail-templates`](/finops/reference/openapi/mail-templates/get-mail-templates): ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/mail-templates' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` A successful request returns an array of all custom templates created. ### Sort and filter custom templates You can sort the returned custom templates by `name` and `type`. You can also filter the results by `name`, `type`, `is_default`, and other fields. For a list of available sort and filter parameters, see the description of the `GET /mail-templates` endpoint. For example, the following request will return all custom templates for credit note emails: ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/mail-templates?type=receivables_credit_note' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` Here are some other filtering examples: * `GET /mail-templates?type=receivables_credit_note&sort=name` - retrieves custom templates for credit note emails and sorts them by name. * `GET /mail-templates?counterpart_name__icontains=invoices` - retrieves all custom template whose name contains "invoices" (case-insensitive). ## Get system templates To retrieve all Tesouro system templates, call [`GET /mail-templates/system`](/finops/reference/openapi/mail-templates/get-mail-templates-system): ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/mail-templates/system' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` A successful response returns an array of all Tesouro system templates. ## Update a template You can update the `language_code`, `body_template`, and `subject_template` properties of a custom template. To update a template, call [`PATCH /mail-templates/{template_id}`](/finops/reference/openapi/mail-templates/patch-mail-templates-id): ```sh lines theme={null} curl -X PATCH 'https://api.sandbox.tesouro.com/v1/mail-templates/5b031d0c...44df31ebf0db' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "body_template": " \n \n \n \n

Contact support if you have already paid this invoice

{{invoice_number}}, {{currency}}, {{discount}} ,{{total_value}}, {{due_date}}, {{entity_name}},{{body_text}}

\n\n", }' ``` A successful request returns an object with the updated custom template details. Only custom templates can be updated or deleted. Tesouro system templates cannot be modified. ## Delete a template To delete an existing custom template, call [`DELETE /mail-templates/{template_id}`](/finops/reference/openapi/mail-templates/delete-mail-templates-id): ```sh lines theme={null} curl -X DELETE 'https://api.sandbox.tesouro.com/v1/mail-templates/5b031d0c...44df31ebf0db' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` A successful request returns a `204` status code with no payload. Default custom templates cannot be deleted. Attempting to delete a default template will return a `409 conflict` error.