Documentation

Found a typo?

You can find this documentation page on GitHub.

Propose a change

Managing templates

In SMTPeter's dashboard it's easy and convenient to manage your templates. All the templates are available by using the REST API. You can then use various methods to download, edit or create templates. And of course you can send email with the templates.

Retrieve templates

Inside your SMTPeter environment you can retrieve the comprehensive list of templates. Do this by making a HTTP GET call to the following URL (don't forget to add your API key):

https://www.smtpeter.com/v1/templates/{start}/{length}

The template method is only available when making a HTTP GET call. If you don't want to be provided with all the templates, it's wise to limit the timeframe with {start} and {length}. The call gives back a JSON array in the following format:

[
    {
        "id"    : 1,
        "name"  : "Test email"
    },
    {   "id"    : 2,
        "name"  : "Test 123"
    }
]

For every template a unique identifier and template name is given back. You can request multiple properties by providing a unique ID when doing an API call.

Request a specific template

You can use the REST API to request a specific template by using the HTTP GET call. Note that you need to have a specific ID from a certain template.

https://www.smtpeter.com/v1/template/{ID}/{format}

You can specify what format you want the returned content to be. You do this by adding the parameter to the URL. The default format is JSON, other formats SMTPeter supports are:

  • JSON: gives back the template in JSON format
  • HTML: gives back the template in HTML format, optimized for emailclients
  • Webversion: gives back the template in HTML format, optimized for webclients
  • MIME: gives back the template in MIME format, with externally hosted images
  • Embedded: gives back the template in MIME format, with embedded images
  • Text: gives back the text version from a template

It's also possible to add extra personalization variables in the GET method, because then your templates will actually be personalized.

If you always give unique names to your templates, it is also possible to retrieve your template by the template's name by instead of passing the template's id, the template's name.

Creating templates

You can build HTML and JSON templates with one of our template editors within the SMTPeter dashboard. But you also can create a new template by using a HTTP POST method and sending it to SMTPeter:

https://www.smtpeter.com/v1/template/{format}

Creating templates is done by adding the JSON code to the body of a POST request. For all specifications of the properties that can be used, you can take a look at: www.ResponsiveEmail.com.

The API gives back a link of the new template in the location header. A JSON object is also sent back, containing the template ID. The data you put in the body must be JSON. It looks like this:

POST /v1/template/html?access_token=yourtoken
Host: www.smtpeter.com
Content-Type: application/json

{ "name" : "template..." }

HTTP/1.1 201 Created
Location: https://www.smtpeter.com/v1/template/2/html?access_token=yourtoken
Content-Type: application/json

{ "id" : 2 }

Updating existing templates

You can also update an existing template. Instead of making a POST request, you make a PUT request. You add the template ID to your JSON from the template you want to update.

PUT /v1/template/html?access_token=yourtoken
Host: www.smtpeter.com
Content-Type: application/json

{ "id" : 2 }

HTTP/1.1 201 Created
Location: https://www.smtpeter.com/v1/template/2/html?access_token=yourtoken
Content-Type: application/json

{ "id" : 2 }

If you always give unique names to your templates, you can also update a template by providing its name instead of the id.

More information