Templates
Use the MailerSend Templates API endpoint to easily manage your transactional email templates. Create, fetch, update, and delete single templates or a list of templates.
Create and manage email templates via the MailerSend API.
Get templates
Retrieve the account templates using this GET request:
GET https://api.mailersend.com/v1/templatesRequest parameters
| Query parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
domain_id | string | no | Existing hashed domain ID. | |
page | int | no | Min: 1 | |
limit | int | no | Min: 10, Max: 100 | Default: 25 |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
// Get all templates of an account
$mailersend->template->getAll();
// Get all templates of a domain
$mailersend->template->getAll('domain_id');
// Get page 2 of templates with 20 records per page
$mailersend->template->getAll('domain_id', 2, 20);Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": [
{
"id": "x8emy5o5world01w",
"name": "Signup email",
"description": null,
"type": "html",
"image_path": "https://link.com/images/image.jpg",
"variables": {
"variables": {},
"personalization": {
"name": "",
"company": ""
}
},
"created_at": "2020-06-10T10:09:56.000000Z",
"updated_at": "2020-06-10T10:09:56.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "Newsletters"
},
"categories": [
{
"id": "5genxmqlgozlyvk7",
"name": "Newsletters"
}
],
"translations": [
{
"language": "es",
"language_name": "Spanish",
"status": "published",
"total_email_sent": 25,
"last_email_sent_at": "2021-06-22T16:00:00.000000Z",
"translated_at": "2021-06-22T15:45:00.000000Z",
"created_at": "2021-06-22T15:40:00.000000Z",
"updated_at": "2021-06-22T15:45:00.000000Z"
}
]
},
{
"id": "x8emy5o5world01x",
"name": "Premium subscription",
"description": null,
"type": "html",
"image_path": "https://link.com/images/image.jpg",
"variables": {
"variables": {},
"personalization": {
"name": "",
"company": ""
}
},
"created_at": "2020-06-10T10:09:56.000000Z",
"updated_at": "2020-06-10T10:09:56.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "Newsletters"
},
"categories": [
{
"id": "5genxmqlgozlyvk7",
"name": "Newsletters"
}
],
"translations": [
{
"language": "es",
"language_name": "Spanish",
"status": "published",
"total_email_sent": 25,
"last_email_sent_at": "2021-06-22T16:00:00.000000Z",
"translated_at": "2021-06-22T15:45:00.000000Z",
"created_at": "2021-06-22T15:40:00.000000Z",
"updated_at": "2021-06-22T15:45:00.000000Z"
}
]
},
{
"id": "x8emy5o5world01y",
"name": "Newsletter",
"description": null,
"type": "html",
"image_path": "https://link.com/images/image.jpg",
"variables": {
"variables": {},
"personalization": {
"name": "",
"company": ""
}
},
"created_at": "2020-06-10T10:09:56.000000Z",
"updated_at": "2020-06-10T10:09:56.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "Newsletters"
},
"categories": [
{
"id": "5genxmqlgozlyvk7",
"name": "Newsletters"
}
],
"translations": [
{
"language": "es",
"language_name": "Spanish",
"status": "published",
"total_email_sent": 25,
"last_email_sent_at": "2021-06-22T16:00:00.000000Z",
"translated_at": "2021-06-22T15:45:00.000000Z",
"created_at": "2021-06-22T15:40:00.000000Z",
"updated_at": "2021-06-22T15:45:00.000000Z"
}
]
}
],
"links": {
"first": "https:\/\/www.mailersend.io\/api\/v1\/templates?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"current_page_url": "https:\/\/www.mailersend.io\/api\/v1\/templates?page=1",
"from": 1,
"path": "https:\/\/www.mailersend.io\/api\/v1\/templates",
"per_page": 25,
"to": 3
}
}Get a single template
Retrieve the information of a single template, its category, domain, and stats using this GET request:
GET https://api.mailersend.com/v1/templates/{template_id}Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
template_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->template->find('template_id');Responses
Valid
{
"data": {
"id": "x8emy5o5world01w",
"name": "libero",
"description": null,
"type": "html",
"image_path": "http://mailersend.com/images/templates/placeholder.png",
"variables": {
"variables": {},
"personalization": {
"name": "",
"elements": [
{
"name": "",
"price": ""
}
],
"license_key": "",
"account_name": "",
"product_name": "",
"renew_button": "",
"expiration_date": ""
}
},
"created_at": "2021-06-22T15:38:51.000000Z",
"updated_at": "2021-06-22T16:00:00.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "aut"
},
"categories": [
{
"id": "5genxmqlgozlyvk7",
"name": "aut"
}
],
"domain": {
"id": "1jreeo",
"name": "domain.com",
"dkim": true,
"spf": true,
"tracking": false,
"is_verified": true,
"is_cname_verified": false,
"is_dns_active": true,
"is_cname_active": false,
"is_tracking_allowed": false,
"has_not_queued_messages": false,
"not_queued_messages_count": 0,
"domain_settings": {
"send_paused": false,
"track_clicks": true,
"track_opens": true,
"track_opens_pixel_on_top": false,
"track_unsubscribe": true,
"track_unsubscribe_html": "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe</a></p>",
"track_unsubscribe_html_enabled": false,
"track_unsubscribe_plain": "Click here to unsubscribe: {{unsubscribe}}",
"track_unsubscribe_plain_enabled": false,
"track_content": true,
"custom_tracking_enabled": false,
"custom_tracking_subdomain": "email",
"return_path_subdomain": "mta",
"inbound_routing_enabled": false,
"inbound_routing_subdomain": "inbound",
"precedence_bulk": false,
"ignore_duplicated_recipients": false
},
"is_sending_paused": false,
"created_at": "2020-06-10T10:09:50.000000Z",
"updated_at": "2020-06-10T10:09:50.000000Z",
"totals": []
},
"translations": [
{
"language": "es",
"language_name": "Spanish",
"status": "published",
"total_email_sent": 25,
"last_email_sent_at": "2021-06-22T16:00:00.000000Z",
"translated_at": "2021-06-22T15:45:00.000000Z",
"created_at": "2021-06-22T15:40:00.000000Z",
"updated_at": "2021-06-22T15:45:00.000000Z"
}
],
"html": "<p>Hi {{ name }}, your license key is {{ license_key }}.</p>",
"text": "Hi {{ name }}, your license key is {{ license_key }}.",
"template_stats": {
"total": 1200,
"queued": 0,
"sent": 4,
"rejected": 16,
"delivered": 1180,
"delivery_rate": "98",
"opened": 590,
"open_rate": "50",
"clicked": 118,
"click_rate": "10",
"unsubscribed": 2,
"unsubscribe_rate": "0",
"complained": 0,
"complain_rate": "0",
"last_email_sent_at": "2026-10-13T09:30:00.000000Z"
}
}
}Error
Response Code: 404 Not FoundTemplate stats
template_stats holds the sending stats for the template.
Note
Template stats are all-time totals for the template and can't be filtered by date. They aren't real-time, so a recent send may not show yet. For stats over a date range, tag your emails and use Activity data by date filtered by tag.
| Field | Type | Details |
|---|---|---|
total | integer | All emails sent with this template, in any status. |
queued | integer | Emails waiting to be sent. |
sent | integer | Emails sent and waiting for a delivery result. |
rejected | integer | Emails that could not be delivered. |
delivered | integer | Emails delivered. |
delivery_rate | string|integer | delivered as a whole-number percentage of total, e.g. "98". 0 when total is 0. |
opened | integer | Delivered emails opened at least once. Each email counts once. |
open_rate | string|integer | opened as a whole-number percentage of delivered, e.g. "50". 0 when delivered is 0. |
clicked | integer | Delivered emails clicked at least once. Each email counts once. |
click_rate | string|integer | clicked as a whole-number percentage of delivered. 0 when delivered is 0. |
unsubscribed | integer | Emails whose recipient unsubscribed. |
unsubscribe_rate | string|integer | unsubscribed as a whole-number percentage of delivered. 0 when delivered is 0. |
complained | integer | Emails the recipient marked as spam. |
complain_rate | string|integer | complained as a whole-number percentage of delivered. 0 when delivered is 0. |
last_email_sent_at | string|null | When an email with this template was last sent. null if none has been sent. |
Create a template
Create a new template using this POST request:
POST https://api.mailersend.com/v1/templatesuse MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TemplateParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$params = (new TemplateParams())
->setName('My Template')
->setHtml('<p>Hello {{name}}</p>')
->setText('Hello {{name}}')
->setDomainId('domain_id')
->setCategories(['category_id'])
->setTags(['transactional', 'welcome']);
$mailersend->template->create($params);Request parameters
JSON parameters are provided in dot notation
| JSON Parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
html | string | yes | Max size of 2 MB. | The HTML body of the template. |
text | string | yes | Max size of 2 MB. | Plain text version. |
name | string | no | Max: 50 | Defaults to "Template" if not provided. |
domain_id | string | no | Existing hashed domain ID. Must belong to the account. | |
categories | array | no | Array of hashed category IDs. Each must belong to the account. | |
tags | array | no | Max: 5 items, each max 191 chars. Tags can't contain URLs, HTML tags or template syntax such as {{ | Array of tag strings to attach to the template. |
Responses
Valid
Response Code: 201 CREATED
Response Headers:
content-type: application/json{
"data": {
"id": "x8emy5o5world01w",
"name": "My Template",
"description": null,
"type": "html",
"image_path": "http://mailersend.com/images/templates/placeholder.png",
"variables": {
"variables": {},
"personalization": {}
},
"created_at": "2021-06-22T15:38:51.000000Z",
"updated_at": "2021-06-22T15:38:51.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "aut"
},
"categories": [
{
"id": "5genxmqlgozlyvk7",
"name": "aut"
}
],
"domain": {
"id": "yjm4ej",
"name": "example.org",
"dkim": true,
"spf": true,
"tracking": false,
"is_verified": true,
"is_cname_verified": false,
"is_dns_active": true,
"is_cname_active": false,
"is_tracking_allowed": false,
"has_not_queued_messages": false,
"not_queued_messages_count": 0,
"domain_settings": {
"send_paused": false,
"track_clicks": true,
"track_opens": true,
"track_opens_pixel_on_top": false,
"track_unsubscribe": true,
"track_unsubscribe_html": "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe</a></p>",
"track_unsubscribe_html_enabled": false,
"track_unsubscribe_plain": "Click here to unsubscribe: {{unsubscribe}}",
"track_unsubscribe_plain_enabled": false,
"track_content": true,
"custom_tracking_enabled": false,
"custom_tracking_subdomain": "email",
"return_path_subdomain": "mta",
"inbound_routing_enabled": false,
"inbound_routing_subdomain": "inbound",
"precedence_bulk": false,
"ignore_duplicated_recipients": false
},
"is_sending_paused": false,
"created_at": "2020-06-10T10:09:50.000000Z",
"updated_at": "2020-06-10T10:09:50.000000Z",
"totals": []
}
}
}Invalid
Response Code: 422 Unprocessable EntitySee - Validation errors
Update a template
Update an existing template using this PUT request. Only templates created via API (origin=api) can be updated — templates created in the MailerSend app return 404.
PUT https://api.mailersend.com/v1/templates/{template_id}use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TemplateParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$params = (new TemplateParams())
->setName('Updated Template Name')
->setHtml('<p>Hello {{name}}, your updated content here.</p>')
->setText('Hello {{name}}, your updated content here.')
->setTags(['transactional']);
$mailersend->template->update('template_id', $params);Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
template_id | string | yes |
JSON parameters are provided in dot notation
| JSON Parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
html | string | no | Max size of 2 MB. | The HTML body of the template. |
text | string | no | Max size of 2 MB. | Plain text version. Auto-generated from HTML if auto_generate is true. |
name | string | no | Max: 50 | |
domain_id | string | no | Existing hashed domain ID. Must belong to the account. | |
categories | array | no | Array of hashed category IDs. Pass an empty array to remove all categories. | |
tags | array | no | Max: 5 items, each max 191 chars. Tags can't contain URLs, HTML tags or template syntax such as {{ | Array of tag strings to attach to the template. |
auto_generate | boolean | no | If true, plain text is auto-generated from the HTML content. |
Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json{
"data": {
"id": "x8emy5o5world01w",
"name": "Updated Template Name",
"description": null,
"type": "html",
"image_path": "http://mailersend.com/images/templates/placeholder.png",
"variables": {
"variables": {},
"personalization": {}
},
"created_at": "2021-06-22T15:38:51.000000Z",
"updated_at": "2021-06-22T16:00:00.000000Z",
"category": {
"id": "5genxmqlgozlyvk7",
"name": "aut"
},
"categories": [
{
"id": "5genxmqlgozlyvk7",
"name": "aut"
}
],
"domain": {
"id": "yjm4ej",
"name": "example.org",
"dkim": true,
"spf": true,
"tracking": false,
"is_verified": true,
"is_cname_verified": false,
"is_dns_active": true,
"is_cname_active": false,
"is_tracking_allowed": false,
"has_not_queued_messages": false,
"not_queued_messages_count": 0,
"domain_settings": {
"send_paused": false,
"track_clicks": true,
"track_opens": true,
"track_opens_pixel_on_top": false,
"track_unsubscribe": true,
"track_unsubscribe_html": "<p>Click here to <a href=\"{{unsubscribe}}\">unsubscribe</a></p>",
"track_unsubscribe_html_enabled": false,
"track_unsubscribe_plain": "Click here to unsubscribe: {{unsubscribe}}",
"track_unsubscribe_plain_enabled": false,
"track_content": true,
"custom_tracking_enabled": false,
"custom_tracking_subdomain": "email",
"return_path_subdomain": "mta",
"inbound_routing_enabled": false,
"inbound_routing_subdomain": "inbound",
"precedence_bulk": false,
"ignore_duplicated_recipients": false
},
"is_sending_paused": false,
"created_at": "2020-06-10T10:09:50.000000Z",
"updated_at": "2020-06-10T10:09:50.000000Z",
"totals": []
}
}
}Invalid
Response Code: 422 Unprocessable EntitySee - Validation errors
Error
Response Code: 404 Not FoundDelete a template
Delete a template with this DELETE request:
DELETE https://api.mailersend.com/v1/templates/{template_id}Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
template_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->template->delete('template_id');Responses
Valid
Response Code: 200 OK
Response Body: [EMPTY]Error
Response Code: 404 Not FoundEmail Survey Templates
Using our drag-and-drop email builder, you may create email templates with a survey block to ask questions and reviews to your recipients. When your recipient receives an email with a survey, they can preview the email and answer your survey questions. Then the responses are sent to your webhook if available.
When a recipient answers all available survey questions the responses are immediately sent to your webhook(if available). However, when a recipient doesn't completely answer all available questions, after an idle time of 30 minutes, the responses would be sent.
Rules and steps for sending an email with a survey include:
- You cannot use the following variables
{{url}},{{survey}},{{survey_last_question}}, as they are reserved. - You must enable
content_trackingon your domain by selecting your domain and enabling the setting under tracking details. Content tracking is a feature available on Starter plans and above. - Add a webhook with the
activity.survey_submittedevent to receive the survey answers. - You can also include the
activity.survey_openedevent in your webhook to know when a recipient has opened an email containing a survey at least once.
Payloads
Example of activity.survey_submitted data sent to your webhook:
{
"type": "activity.survey_submitted",
"created_at": "2025-08-06T00:20:36.589903Z",
"data": {
"id": "68929fd47f916891ef12eba9",
"domain_id": "7nxe3yjmeq28vp0k",
"message_id": "68929fd402fd7079a02cf858",
"email_id": "68929fd47f916891ef12eba9",
"type": "survey_submitted",
"subject": "Test email",
"from": "test@domain.com",
"tags": [
"test2",
"test3"
],
"meta": {
"surveys": [
{
"question_id": 1,
"survey_id": 1,
"answer": "test",
"is_last_question": true
}
]
}
}
}Recipients
Manage your email recipients with ease using MailerSend's Recipients API. Get, create, update recipients and more with a simple API call. Learn more.
Email Verification
Verify a single email address or in bulk with MailerSend's Email Verification API. Create and fetch lists and retrieve your results.