Create and manage email templates

The /mail-templates* endpoints require a app access token.

Create an email template

To create a custom email template, call 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. 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:

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": "<!DOCTYPE html> \n <html lang=\"en\">\n <body>\n <ul id=\"navigation\">\n<li>\n<h1>Dear {{company_name}},\n\nThank you for your business!\nPlease pay the balance of {{amount_due}} (invoice #{{invoice_number}}) by {{due_date}}.\n\nFor any questions or concerns, please don’t hesitate to get in touch with us at {{entity_email}}. We look forward to serving you again and wish you all the best!</h1>\n<a href=\"{{ payment_link }}\">Pay Invoice Now!</a>\n</li>\n</ul>\n<h1></h1>\n</body>\n</html>",
       "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. 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.

{
  "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": "<!DOCTYPE html> \n <html lang=\"en\">\n <body>\n <ul id=\"navigation\">\n<li>\n<h1>Dear {{company_name}},\n\nThank you for your business!\nPlease pay the balance of {{amount_due}} (invoice #{{invoice_number}}) by {{due_date}}.\n\nFor any questions or concerns, please don’t hesitate to get in touch with us at {{entity_email}}. We look forward to serving you again and wish you all the best!</h1>\n<a href=\"{{ payment_link }}\">Pay Invoice Now!</a>\n</li>\n</ul>\n<h1></h1>\n</body>\n</html>",
  "created_at": "2023-12-01T16:04:59.177241+00:00",
  "updated_at": "2023-12-01T16:04:59.177255+00:00"
}

Default templatesYou 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} endpoint:

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:

{
  "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": "<!DOCTYPE html> \n <html lang=\"en\">\n <body>\n <ul id=\"navigation\">\n<li>\n<h1>Dear {{company_name}},\n\nThank you for your business!\nPlease view the quotation for the items requested..\n\nFor any questions or concerns, please don’t hesitate to get in touch with us at {{entity_email}}. We look forward to serving you and wish you all the best!</h1>\n<a href=\"{{quote_accept_page_url}}\">Accept quote Now!</a>\n</li>\n</ul>\n<h1></h1>\n</body>\n</html>",
  "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:

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:

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:

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:

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:

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}:

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": "<!DOCTYPE html> \n <html lang=\"en\">\n <body>\n <ul id=\"navigation\">\n<li>\n<a href=\"{{ payment_link }}\">Pay Invoice Now!</a>\n</li>\n</ul>\n<h1><p>Contact support if you have already paid this invoice</p>{{invoice_number}}, {{currency}}, {{discount}} ,{{total_value}}, {{due_date}}, {{entity_name}},{{body_text}}</h1>\n</body>\n</html>",
     }'

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}:

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.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Create and manage email templates

Create an email template

Retrieve a template

Set template as default

Preview mail templates

Get all templates

Sort and filter custom templates

Get system templates

Update a template

Delete a template

​Create an email template

​Retrieve a template

​Set template as default

​Preview mail templates

​Get all templates

​Sort and filter custom templates

​Get system templates

​Update a template

​Delete a template

Create an email template

Retrieve a template

Set template as default

Preview mail templates

Get all templates

Sort and filter custom templates

Get system templates

Update a template

Delete a template