Templates

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

Get templates

get/v3/{domainId}/templates

Returns a list of templates for the domain.

SecuritybasicAuth
Request
path Parameters
domain
required
string

Domain name to fetch the templates for.

query Parameters
page
required
string

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

limit
required
integer

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

p
required
string

Pivot used to retrieve the next page of templates.

Responses
200

A 200 response

Response Schema: application/json
items
required
Array of objects
required
object
Request samples 
Response samples 
application/json
{}
Create a template
post/v3/{domainId}/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
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.


 
template
boolean
Content of the template.


 
description
string
Description of the template being stored


 
engine
string
The template engine to be used when rendering the template. Supported value are handlebars and go (golang template).  The default if parameter is not provided is handlebars.


 
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


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


 
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/{domainId}/templates
Delete all templates and their versions for the domain.


SecuritybasicAuth 
Request 
path Parameters
domain
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/{domainId}/templates/{templateId}/versions
Returns a paginated list of template versions.


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


 
templateId
required
string
template name to fetch the versions for.


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


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


 
p
required
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/{domainId}/templates/{templateId}/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
required
string
Domain name the template is associated with.


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


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


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


 
engine
string
The template engine to be used when rendering the template. Supported value are handlebars and go (golang template).  The default if parameter is not provided is handlebars.


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


 
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


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


 
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/{domainId}/templates/{templateId}
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
required
string
Domain name the template is stored under.


 
templateId
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
 
description
required
string
 
createdAt
required
string
 
createdBy
required
string
 
id
required
string
 
versions
Array of objects
 
object
 
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/{domainId}/templates/{templateId}
Update the description of a template.


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


 
templateId
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/{domainId}/templates/{templateId}
Delete the template specified in the url. NOTE: This method deletes all versions of the specified template.


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


 
templateId
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/{domainId}/templates/{templateId}/versions/{versionId}
Retrieve the information and content of the specified version of a template.


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


 
templateId
required
string
template name the version is for.


 
versionId
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
 
description
required
string
 
createdAt
required
string
 
createdBy
required
string
 
id
required
string
 
versions
Array of objects
 
object
 
Request samples 
Response samples 
application/json
{
  • "template": {
    • "id": "46565d87-68b6-4edb-8b3c-34554af4bb77",
    • "version": {
      },
    • "name": "template_name",
    • "description": "This is the description of the template",
    • "createdAt": "Sat, 12 Nov 1955 06:38:00 UTC",
    • "createdBy": "user-supplied-value"
    }
}
Update a version
put/v3/{domainId}/templates/{templateId}/versions/{versionId}
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
required
string
Domain name the template is associated with.


 
templateId
required
string
template name the version is stored under.


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


 
Request Body schema: multipart/form-data
required
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.


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


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


 
template
boolean
Content of the template.


 
engine
string
The template engine to be used when rendering the template. Supported value are handlebars and go (golang template).


 
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": {
    • "version": {
      },
    • "name": "template_name"
    }
}
Delete a version
delete/v3/{domainId}/templates/{templateId}/versions/{versionId}
Delete a specific template version.


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


 
templateId
required
string
template name the version is stored under.


 
versionId
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
{
  • "template": {
    • "name": "template_name",
    • "version": {
      }
    },
  • "message": "version has been deleted"
}
Copy a version
put/v3/{domainId}/templates/{templateId}/versions/{versionId}/copy/{versionIdTo}
Copies an existing version into a new version of a different tag name.


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


 
templateId
required
string
template name the version is stored under.


 
versionId
required
string
Tag of the version to copy.


 
versionIdTo
required
string
Version tag to copy version to. Version cannot already exist.


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


 
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": {
      }
    }
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.