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/templates

Request parameters

Query parameter	Type	Required	Limitations	Details
`domain_id`	`string`	no
`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);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend} from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.template.list({
    domain_id: "domain_id"
})
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import MailerSendClient, TemplatesBuilder

ms = MailerSendClient()

request = (TemplatesBuilder()
          .domain_id("domain-id")
          .page(1)
          .limit(25)
          .build_templates_list_request())

response = ms.templates.list_templates(request)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	
	options := &mailersend.ListTemplateOptions{
		Page:  1,
		Limit: 25,
	}
	
	_, _, err := ms.Template.List(ctx, options)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.TemplateItem;
import com.mailersend.sdk.templates.TemplatesList;

public void getTemplatesList() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
            TemplatesList list = ms.templates().getTemplates();
            
            for (TemplateItem item : list.templates) {
                
                System.out.println(item.id);
                System.out.println(item.name);
            }
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_templates = Mailersend::Templates.new
ms_templates.list(domain_id: "aax455lll", page: 1, limit: 10)

More examplesopen in new window

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",
        "tags": ["transactional", "welcome"],
        "variables": {
          "name": "",
          "company": ""
        },
        "created_at": "2020-06-10 10:09:56",
        "updated_at": "2020-06-10 10:09:56"
      },
      {
        "id": "x8emy5o5world01x",
        "name": "Premium subscription",
        "description": null,
        "type": "html",
        "image_path": "https://link.com/images/image.jpg",
        "tags": [],
        "variables": null,
        "created_at": "2020-06-10 10:09:56",
        "updated_at": "2020-06-10 10:09:56"
      },
      {
        "id": "x8emy5o5world01y",
        "name": "Newsletter",
        "description": null,
        "type": "html",
        "image_path": "https://link.com/images/image.jpg",
        "tags": [],
        "variables": null,
        "created_at": "2020-06-10 10:09:56",
        "updated_at": "2020-06-10 10:09:56"
      }
  ],
  "links": {
    "first": "https:\/\/www.mailersend.io\/api\/v1\/templates?page=1",
    "last": "https:\/\/www.mailersend.io\/api\/v1\/templates?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https:\/\/www.mailersend.io\/api\/v1\/templates",
    "per_page": 25,
    "to": 3,
    "total": 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');

More examplesopen in new window

import 'dotenv/config';
import { MailerSend} from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.template.single("template_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import MailerSendClient, TemplatesBuilder

ms = MailerSendClient()

request = (TemplatesBuilder()
          .template("template-id")
          .build_template_get_request())

response = ms.templates.get_template(request)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	
	templateID := "template-id"
	
	_, _, err := ms.Template.Get(ctx, templateID)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;
import com.mailersend.sdk.templates.TemplateItem;
import com.mailersend.sdk.templates.TemplatesList;

public void getTemplate() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
            Template template = ms.templates().getTemplate("template id");
            
            System.out.println(template.id);
            System.out.println(template.name);
            System.out.println(template.imagePath);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_templates = Mailersend::Templates.new
ms_templates.single(template_id: "id124")

More examplesopen in new window

Responses

Valid

{
  "data": {
    "id": "x8emy5o5world01w",
    "name": "libero",
    "description": null,
    "type": "html",
    "image_path": "http://mailersend.com/images/templates/placeholder.png",
    "variables": {
      "name": "",
      "elements": [
        {
          "name": "",
          "price": ""
        }
      ],
      "license_key": "",
      "account_name": "",
      "product_name": "",
      "renew_button": "",
      "expiration_date": ""
    },
    "tags": ["transactional"],
    "created_at": "2021-06-22T15:38:51.000000Z",
    "updated_at": "2021-06-22T16:00:00.000000Z",
    "category": {
      "id": "5genxmqlgozlyvk7",
      "name": "aut"
    },
    "domain": {
      "id": "1jreeo",
      "name": "domain.com",
      "...",
      "domain_settings": {
        "..."
      },
      "totals": {
        "hard_bounced": 25,
        "soft_bounced": 40,
        "sent": 231,
        "delivered": 109
      }
    },
    "template_stats": {
      "total": 0,
      "queued": 0,
      "sent": 0,
      "rejected": 0,
      "delivered": 0,
      "last_email_sent_at": null
    }
  }
}

Error

Response Code: 404 Not Found

Create a template

Create a new template using this POST request:

POST https://api.mailersend.com/v1/templates

use 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);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend, EmailTemplate } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const template = new EmailTemplate()
  .setName("My Template")
  .setHtml("<p>Hello {{name}}</p>")
  .setText("Hello {{name}}")
  .setDomainId("domain_id")
  .setCategories(["category_id"])
  .setTags(["transactional", "welcome"]);

mailerSend.email.template.create(template)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import MailerSendClient, TemplatesBuilder

ms = MailerSendClient()

request = (TemplatesBuilder()
          .name("My Template")
          .html("<p>Hello {{name}}</p>")
          .text("Hello {{name}}")
          .domain_id("domain-id")
          .categories(["category-id"])
          .tags(["transactional", "welcome"])
          .build_template_create_request())

response = ms.templates.create_template(request)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	createOptions := &mailersend.CreateTemplateOptions{
		Name:       "My Template",
		Html:       "<p>Hello {{name}}</p>",
		Text:       "Hello {{name}}",
		DomainID:   "domain-id",
		Categories: []string{"category-id"},
		Tags:       []string{"transactional", "welcome"},
	}

	_, _, err := ms.Template.Create(ctx, createOptions)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;

public void createTemplate() {

    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");

    try {

        Template template = ms.templates().builder()
            .name("My Template")
            .html("<p>Hello {{name}}</p>")
            .text("Hello {{name}}")
            .domainId("domain-id")
            .addCategory("category-id")
            .addTag("transactional")
            .create();

        System.out.println(template.id);
        System.out.println(template.name);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_templates = Mailersend::Templates.new
ms_templates.create(
  name: "My Template",
  html: "<p>Hello {{name}}</p>",
  text: "Hello {{name}}",
  domain_id: "domain_id",
  categories: ["category_id"],
  tags: ["transactional", "welcome"]
)

More examplesopen in new window

Request parameters

JSON parameters are provided in dot notation

JSON Parameter	Type	Required	Limitations	Details
`html`	`string`	yes		The HTML body of the template.
`text`	`string`	yes		Plain text version. Auto-generated from HTML if `auto_generate` is `true`.
`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	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: 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": null,
    "tags": ["transactional", "welcome"],
    "created_at": "2021-06-22T15:38:51.000000Z",
    "updated_at": "2021-06-22T15:38:51.000000Z",
    "category": null,
    "domain": null
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - 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);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend, EmailTemplate } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const template = new EmailTemplate()
  .setName("Updated Template Name")
  .setHtml("<p>Hello {{name}}, your updated content here.</p>")
  .setText("Hello {{name}}, your updated content here.")
  .setTags(["transactional"]);

mailerSend.email.template.update("template_id", template)
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import MailerSendClient, TemplatesBuilder

ms = MailerSendClient()

request = (TemplatesBuilder()
          .template("template-id")
          .name("Updated Template Name")
          .html("<p>Hello {{name}}, your updated content here.</p>")
          .text("Hello {{name}}, your updated content here.")
          .tags(["transactional"])
          .build_template_update_request())

response = ms.templates.update_template(request)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	templateID := "template-id"

	updateOptions := &mailersend.UpdateTemplateOptions{
		Name: "Updated Template Name",
		Html: "<p>Hello {{name}}, your updated content here.</p>",
		Text: "Hello {{name}}, your updated content here.",
		Tags: []string{"transactional"},
	}

	_, _, err := ms.Template.Update(ctx, templateID, updateOptions)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;

public void updateTemplate() {

    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");

    try {

        Template template = ms.templates().builder()
            .name("Updated Template Name")
            .html("<p>Hello {{name}}, your updated content here.</p>")
            .text("Hello {{name}}, your updated content here.")
            .addTag("transactional")
            .update("template-id");

        System.out.println(template.id);
        System.out.println(template.name);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_templates = Mailersend::Templates.new
ms_templates.update(
  template_id: "template_id",
  name: "Updated Template Name",
  html: "<p>Hello {{name}}, your updated content here.</p>",
  text: "Hello {{name}}, your updated content here.",
  tags: ["transactional"]
)

More examplesopen in new window

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		The HTML body of the template.
`text`	`string`	no		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	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": null,
    "tags": ["transactional"],
    "created_at": "2021-06-22T15:38:51.000000Z",
    "updated_at": "2021-06-22T16:00:00.000000Z",
    "category": null,
    "domain": null
  }
}

Invalid

Response Code: 422 Unprocessable Entity

See - Validation errors

Error

Response Code: 404 Not Found

Delete 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');

More examplesopen in new window

import 'dotenv/config';
import { MailerSend} from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.template.delete("template_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

More examplesopen in new window

from mailersend import MailerSendClient, TemplatesBuilder

ms = MailerSendClient()

request = (TemplatesBuilder()
          .template("template-id")
          .build_delete_request())

response = ms.templates.delete_template(request)

More examplesopen in new window

package main

import (
	"context"
	"log"
	"time"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	templateID := "template-id"
	
	_, err := ms.Template.Delete(ctx, templateID)
	if err != nil {
		log.Fatal(err)
	}
}

More examplesopen in new window

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.templates.Template;
import com.mailersend.sdk.templates.TemplateItem;
import com.mailersend.sdk.templates.TemplatesList;

public void deleteTemplate() {
    
    MailerSend ms = new MailerSend();
    ms.setToken("mailersend token");
    
    try {
        
            MailerSendResponse response = ms.templates().deleteTemplate("template id");
            
            System.out.println(response.responseStatusCode);
        
    } catch (MailerSendException e) {
        
        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_templates = Mailersend::Templates.new
ms_templates.delete(template_id: "id124")

More examplesopen in new window

Responses

Valid

Response Code: 200 OK
Response Body: [EMPTY]

Error

Response Code: 404 Not Found

# Templates

# Get templates

# Request parameters

# Responses

# Valid

# Get a single template

# Request parameters

# Responses

# Valid

# Error

# Create a template

# Request parameters

# Responses

# Valid

# Invalid

# Update a template

# Request parameters

# Responses

# Valid

# Invalid

# Error

# Delete a template

# Request parameters

# Responses

# Valid

# Error

Templates

Get templates

Request parameters

Responses

Valid

Get a single template

Request parameters

Responses

Valid

Error

Create a template

Request parameters

Responses

Valid

Invalid

Update a template

Request parameters

Responses

Valid

Invalid

Error

Delete a template

Request parameters

Responses

Valid

Error