Create and manage email templates

The /mail_templates* endpoints require a partner 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 Monite’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:

1curl -X POST 'https://api.sandbox.monite.com/v1/mail_templates' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4     -H 'Content-Type: application/json' \
5     -d '{
6       "language": "en",
7       "subject_template": "New invoice from {{entity_name}}!",
8       "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>",
9       "name": "New invoice template",
10       "type": "receivables_invoice",
11       "is_default": true
12     }'

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.

1{
2  "id": "5b031d0c-dcb6-4aa0-b660-44df31ebf0db",
3  "type": "receivables_invoice",
4  "name": "New invoice template",
5  "is_default": true,
6  "language": "en",
7  "subject_template": "New invoice from {{entity_name}}!",
8  "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>",
9  "created_at": "2023-12-01T16:04:59.177241+00:00",
10  "updated_at": "2023-12-01T16:04:59.177255+00:00"
11}

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

1curl -X GET 'https://api.sandbox.monite.com/v1/mail_templates/44df31ebf0db...5b031d0c' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

A successful response returns information about the custom template with the specified ID:

1{
2  "id": "44df31ebf0db-dcb6-4aa0-b660-5b031d0c",
3  "type": "receivables_quote",
4  "name": "New quote template",
5  "is_default": false,
6  "language": "en",
7  "subject_template": "New invoice from {{entity_name}}!",
8  "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>",
9  "created_at": "2023-12-11T16:04:59.177241+00:00",
10  "updated_at": "2023-12-12T19:54:59.177255+00:00"
11}

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:

1curl -X POST 'https://api.sandbox.monite.com/v1/mail_templates/44df31ebf0db...5b031d0c/make_default' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_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 Monite’s system template or your custom template.

To preview a mail template, call POST /mail_templates/preview:

1curl -X POST 'https://api.sandbox.monite.com/v1/mail_templates/preview' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer ACCESS_TOKEN' \
4     -H 'Content-Type: application/json' \
5     -d '{
6       "body": "Find attached the current rates for the items requested",
7       "document_type": "receivables_quote",
8       "language_code": "en",
9       "subject": "Your new quote is here"
10     }'
  • 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:

1curl -X GET 'https://api.sandbox.monite.com/v1/mail_templates' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_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:

1curl -X GET 'https://api.sandbox.monite.com/v1/mail_templates?type=receivables_credit_note' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_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 Monite system templates, call GET /mail_templates/system:

1curl -X GET 'https://api.sandbox.monite.com/v1/mail_templates/system' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

A successful response returns an array of all Monite 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}:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/mail_templates/5b031d0c...44df31ebf0db' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4     -H 'Content-Type: application/json' \
5     -d '{
6       "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>",
7     }'

A successful request returns an object with the updated custom template details.

Only custom templates can be updated or deleted. Monite system templates cannot be modified.

Delete a template

To delete an existing custom template, call DELETE /mail_templates/{template_id}:

1curl -X DELETE 'https://api.sandbox.monite.com/v1/mail_templates/5b031d0c...44df31ebf0db' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'Authorization: Bearer YOUR_PARTNER_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.