Templates

This API allows you to store predefined templates and use them to send messages using the Sending API.

Get templates

get/v3/{domain_name}/templates

Returns a list of templates for the domain.

SecuritybasicAuth
Request
path Parameters
domain_name
required
string

Domain name to fetch the templates for.

query Parameters
page
string

Name of the page to retrieve. Value can be first, last, next, or previous. Defaults to first.

Enum Value Description
first

Get the first list's page

last

Get the last list's page

next

Get the next list's page

previous

Get the previous list's page

limit
integer

Number of templates to retrieve. Default and max limit is 100.

p
string

Pivot used to retrieve the next page of templates.

Responses
200

A 200 response

Response Schema: application/json
required
Array of objects
required
object
Request samples 
Response samples 
application/json
{}
Create a template
post/v3/{domain_name}/templates
Store a new template, including its name, description and (optionally) the template content. If the template content is provided, a new version is automatically created and becomes the active version.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
Request Body schema: multipart/form-data
required
name
required
string
Name of the template being stored. Supports utf-8 characters and name will be down cased.


 
description
string
Description of the template being stored


 
createdBy
string
Optional metadata field api user can indicate who created the template.


 
template
string
Content of the template.


 
tag
string
Initial tag of the created version. If the template parameter is provided and the tag is missing, the default value initial is used.


 
comment
string
Version comment. This is valid only if a new version is being created. (template parameter is provided.)


 
headers
string
Key Value json dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names From, Subject, and Reply-To are the only ones currently supported.  These headers will be inserted into the mime at the time we attempt delivery. 


Headers set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to postmaster@your-sending-domain.tld


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
Request samples 
Response samples 
application/json
{
  • "message": "template has been stored",
  • "template": {
    • "name": "template_name",
    • "description": "This is the description of the template",
    • "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC",
    • "createdBy": "user-supplied-value",
    • "id": "46565d87-68b6-4edb-8b3c-34554af4bb77",
    • "version": {
      }
    }
}
Delete all templates
delete/v3/{domain_name}/templates
Delete all templates and their versions for the domain.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
Request samples 
Response samples 
application/json
{
  • "message": "templates have been deleted"
}
Get all template versions
get/v3/{domain_name}/templates/{template_name}/versions
Returns a paginated list of template versions.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name to fetch the templates for.


 
template_name
required
string
template name to fetch the versions for.


 
query Parameters
page
string
Name of the page to retrieve. Value can be first, last, next, or previous. Defaults to first.


 Enum Value Description
first
Get the first list's page


last
Get the last list's page


next
Get the next list's page


previous
Get the previous list's page


 
limit
integer
Number of templates to retrieve. Default and max limit is 100.


 
p
string
Pivot used to retrieve the next page of templates.


 
Responses 
200
A 200 response


Response Schema: application/json
required
object
 
required
object
 
Request samples 
Response samples 
application/json
{}
Create a template version
post/v3/{domain_name}/templates/{template_name}/versions
Adds a new template version. If the template doesn’t contain any other versions, the first version becomes active. A template can store up to 40 versions.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
template_name
required
string
template name to create the new version for.


 
Request Body schema: multipart/form-data
required
template
required
string
Content of the template.


 
tag
required
string
Tag of the version that is being created. Must be unique to the template.


 
comment
string
Comment related to the version that is being created.


 
active
string
If this flag is set to yes, this version becomes active


 
headers
string
Key Value json dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names From, Subject, and Reply-To are the only ones currently supported.  These headers will be inserted into the mime at the time we attempt delivery. 


Headers set at the message level will override headers set on the template. e.g. Setting the From header at the time of sending will override the From header saved on the template. Additionally, headers generated by templates are not reflected on the accepted event as they are not prepended to the message until the message is prepped for delivery. if a From header is not provided either in the message or template, we will default to postmaster@your-sending-domain.tld


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
Request samples 
Response samples 
application/json
{
  • "message": "new version of the template has been stored",
  • "template": {
    • "name": "template_name",
    • "description": "This is the description of the template",
    • "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC",
    • "createdBy": "user-supplied-value",
    • "id": "46565d87-68b6-4edb-8b3c-34554af4bb77",
    • "version": {
      }
    }
}
Get template
get/v3/{domain_name}/templates/{template_name}
Returns metadata information about the stored template specified in the url. If the active flag is provided, the content of the active version of the template is returned.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is stored under.


 
template_name
required
string
Template name to fetch.


 
query Parameters
active
string
If this flag is set to yes the active version of the template is included in the response.


 
Responses 
200
A 200 response


Response Schema: application/json
required
object
 
name
required
string
Name of the template


 
description
string
Description of the template


 
createdAt
string
Creation date in RFC822 format


 
createdBy
string
Indicate who created the template


 
id
string
 
object
Active version information


 
Array of objects
List of template's versions


 
Request samples 
Response samples 
application/json
{
  • "template": {
    • "name": "template_name",
    • "description": "This is the description of the template",
    • "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC",
    • "createdBy": "user-supplied-value",
    • "id": "46565d87-68b6-4edb-8b3c-34554af4bb77",
    • "version": {
      }
    }
}
Update template
put/v3/{domain_name}/templates/{template_name}
Update the description of a template.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
template_name
required
string
The template name.


 
Request Body schema: multipart/form-data
required
description
string
Update description of the template being updated.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
Request samples 
Response samples 
application/json
{
  • "message": "template has been updated",
  • "template": {
    • "name": "template_name"
    }
}
Delete a template
delete/v3/{domain_name}/templates/{template_name}
Delete the template specified in the url. NOTE: This method deletes all versions of the specified template.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
template_name
required
string
template name to be deleted.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
Request samples 
Response samples 
application/json
{
  • "message": "template has been deleted",
  • "template": {
    • "name": "template_name"
    }
}
Get a version
get/v3/{domain_name}/templates/{template_name}/versions/{version_name}
Retrieve the information and content of the specified version of a template.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is stored under.


 
template_name
required
string
template name the version is for.


 
version_name
required
string
Tag of the version of the template to fetch.


 
Responses 
200
A 200 response


Response Schema: application/json
required
object
 
name
required
string
Name of the template


 
description
string
Description of the template


 
createdAt
string
Creation date in RFC822 format


 
createdBy
string
Indicate who created the template


 
id
string
 
object
Active version information


 
Array of objects
List of template's versions


 
Request samples 
Response samples 
application/json
{
  • "template": {
    • "name": "template_name",
    • "description": "This is the description of the template",
    • "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC",
    • "createdBy": "user-supplied-value",
    • "id": "46565d87-68b6-4edb-8b3c-34554af4bb77",
    • "version": {
      }
    }
}
Update a version
put/v3/{domain_name}/templates/{template_name}/versions/{version_name}
Update information or content of the specific template version. Existing fields not included in the request will not be changed


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
template_name
required
string
template name the version is stored under.


 
version_name
required
string
Tag of the version of the template to be updated


 
Request Body schema: multipart/form-data
required
template
string
Content of the template.


 
comment
string
Comment related to the version that is being created.


 
active
string
If this flag is set to yes, this version becomes active


 
headers
string
Key Value json dictionary of headers to be stored with the template. Where key is the header name and value is the header value. The header names From, Subject, and Reply-To are the only ones currently supported.  These headers will be inserted into the mime at the time we attempt delivery.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
Request samples 
Response samples 
application/json
{
  • "message": "version has been updated",
  • "template": {
    • "name": "template_name",
    • "version": {
      }
    }
}
Delete a version
delete/v3/{domain_name}/templates/{template_name}/versions/{version_name}
Delete a specific template version.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
template_name
required
string
template name the version is stored under.


 
version_name
required
string
Tag of the version of the template to be deleted.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
 
Request samples 
Response samples 
application/json
{
  • "message": "version has been deleted",
  • "template": {
    • "name": "template_name",
    • "version": {
      }
    }
}
Copy a version
put/v3/{domain_name}/templates/{template_name}/versions/{version_name}/copy/{new_version_name}
Copies an existing version into a new version with the provided name.


SecuritybasicAuth 
Request 
path Parameters
domain_name
required
string
Domain name the template is associated with.


 
template_name
required
string
template name the version is stored under.


 
version_name
required
string
Tag of the version to copy.


 
new_version_name
required
string
The name for the new version. If the version name already exists, it will be overridden.


 
query Parameters
comment
string
Comment to be used for the new version.


 
Responses 
200
A 200 response


Response Schema: application/json
message
required
string
 
required
object
Created version information


 
required
object
 Deprecated 
Deprecated: Use 'version' field


 
Request samples 
Response samples 
application/json
{
  • "message": "version has been copied",
  • "version": {
    • "tag": "cloned version",
    • "template": "<p>{{firstname}} {{lastname}}</p>",
    • "engine": "handlebars",
    • "createdAt": "Fri, 21 Mar 2025 15:00:44 UTC",
    • "comment": "a comment value from copy",
    • "id": "95658c55-e93a-40d5-a02f-a4fadfbbb3ca"
    }
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.