curl

Choose Language

Templates Calls

/templates/add.json

Add a new template

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","name":"Example Template","from_email":"from_email@example.com","from_name":"Example Name","subject":"example subject","code":"<div>example code<\/div>","text":"Example text content","publish":false,"labels":["example-label"]}' 'https://mandrillapp.com/api/1.0/templates/add.json'

Example Response

{"slug":"example-template","name":"Example Template","labels":["example-label"],"code":"<div mc:edit=\"editable\">editable content<\/div>","subject":"example subject","from_email":"from.email@example.com","from_name":"Example Name","text":"Example text","publish_name":"Example Template","publish_code":"<div mc:edit=\"editable\">different than draft content<\/div>","publish_subject":"example publish_subject","publish_from_email":"from.email.published@example.com","publish_from_name":"Example Published Name","publish_text":"Example published text","published_at":"2013-01-01 15:30:40","created_at":"2013-01-01 15:30:27","updated_at":"2013-01-01 15:30:49"}

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
name* string the name for the new template - must be unique
Validation: required
from_email string a default sending address for emails sent using this template
Validation: email
from_name string a default from name to be used
subject string a default subject line to be used
code string the HTML code for the template with mc:edit attributes for the editable elements
text string a default text part to be used when sending with this template
publish boolean set to false to add a draft template without publishing
labels array an optional array of up to 10 labels to use for filtering templates
labels[] string a single label
maxlength(100)
Return Value
struct the information saved about the new template
slug string the immutable unique code name of the template
name string the name of the template
labels array the list of labels applied to the template
labels[] string a single label
code string the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
subject string the subject line of the template, if provided - draft version
from_email string the default sender address for the template, if provided - draft version
from_name string the default sender from name for the template, if provided - draft version
text string the default text part of messages sent with the template, if provided - draft version
publish_name string the same as the template name - kept as a separate field for backwards compatibility
publish_code string the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
publish_subject string the subject line of the template, if provided
publish_from_email string the default sender address for the template, if provided
publish_from_name string the default sender from name for the template, if provided
publish_text string the default text part of messages sent with the template, if provided
published_at string the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
created_at string the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
updated_at string the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Template The given template name already exists or contains invalid characters
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/info.json

Get the information for an existing template

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","name":"Example Template"}' 'https://mandrillapp.com/api/1.0/templates/info.json'

Example Response

{"slug":"example-template","name":"Example Template","labels":["example-label"],"code":"<div mc:edit=\"editable\">editable content<\/div>","subject":"example subject","from_email":"from.email@example.com","from_name":"Example Name","text":"Example text","publish_name":"Example Template","publish_code":"<div mc:edit=\"editable\">different than draft content<\/div>","publish_subject":"example publish_subject","publish_from_email":"from.email.published@example.com","publish_from_name":"Example Published Name","publish_text":"Example published text","published_at":"2013-01-01 15:30:40","created_at":"2013-01-01 15:30:27","updated_at":"2013-01-01 15:30:49"}

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
name* string the immutable name of an existing template
Validation: required
Return Value
struct the requested template information
slug string the immutable unique code name of the template
name string the name of the template
labels array the list of labels applied to the template
labels[] string a single label
code string the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
subject string the subject line of the template, if provided - draft version
from_email string the default sender address for the template, if provided - draft version
from_name string the default sender from name for the template, if provided - draft version
text string the default text part of messages sent with the template, if provided - draft version
publish_name string the same as the template name - kept as a separate field for backwards compatibility
publish_code string the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
publish_subject string the subject line of the template, if provided
publish_from_email string the default sender address for the template, if provided
publish_from_name string the default sender from name for the template, if provided
publish_text string the default text part of messages sent with the template, if provided
published_at string the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
created_at string the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
updated_at string the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_Template The requested template does not exist
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/update.json

Update the code for an existing template. If null is provided for any fields, the values will remain unchanged.

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","name":"Example Template","from_email":"from_email@example.com","from_name":"Example Name","subject":"example subject","code":"<div>new example code<\/div>","text":"Example text content","publish":false,"labels":["example-label"]}' 'https://mandrillapp.com/api/1.0/templates/update.json'

Example Response

{"slug":"example-template","name":"Example Template","labels":["example-label"],"code":"<div mc:edit=\"editable\">editable content<\/div>","subject":"example subject","from_email":"from.email@example.com","from_name":"Example Name","text":"Example text","publish_name":"Example Template","publish_code":"<div mc:edit=\"editable\">different than draft content<\/div>","publish_subject":"example publish_subject","publish_from_email":"from.email.published@example.com","publish_from_name":"Example Published Name","publish_text":"Example published text","published_at":"2013-01-01 15:30:40","created_at":"2013-01-01 15:30:27","updated_at":"2013-01-01 15:30:49"}

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
name* string the immutable name of an existing template
Validation: required
from_email string the new default sending address
Validation: email
from_name string the new default from name
subject string the new default subject line
code string the new code for the template
text string the new default text part to be used
publish boolean set to false to update the draft version of the template without publishing
labels array an optional array of up to 10 labels to use for filtering templates
labels[] string a single label
maxlength(100)
Return Value
struct the template that was updated
slug string the immutable unique code name of the template
name string the name of the template
labels array the list of labels applied to the template
labels[] string a single label
code string the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
subject string the subject line of the template, if provided - draft version
from_email string the default sender address for the template, if provided - draft version
from_name string the default sender from name for the template, if provided - draft version
text string the default text part of messages sent with the template, if provided - draft version
publish_name string the same as the template name - kept as a separate field for backwards compatibility
publish_code string the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
publish_subject string the subject line of the template, if provided
publish_from_email string the default sender address for the template, if provided
publish_from_name string the default sender from name for the template, if provided
publish_text string the default text part of messages sent with the template, if provided
published_at string the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
created_at string the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
updated_at string the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_Template The requested template does not exist
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/publish.json

Publish the content for the template. Any new messages sent using this template will start using the content that was previously in draft.

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","name":"Example Template"}' 'https://mandrillapp.com/api/1.0/templates/publish.json'

Example Response

{"slug":"example-template","name":"Example Template","labels":["example-label"],"code":"<div mc:edit=\"editable\">editable content<\/div>","subject":"example subject","from_email":"from.email@example.com","from_name":"Example Name","text":"Example text","publish_name":"Example Template","publish_code":"<div mc:edit=\"editable\">different than draft content<\/div>","publish_subject":"example publish_subject","publish_from_email":"from.email.published@example.com","publish_from_name":"Example Published Name","publish_text":"Example published text","published_at":"2013-01-01 15:30:40","created_at":"2013-01-01 15:30:27","updated_at":"2013-01-01 15:30:49"}

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
name* string the immutable name of an existing template
Validation: required
Return Value
struct the template that was published
slug string the immutable unique code name of the template
name string the name of the template
labels array the list of labels applied to the template
labels[] string a single label
code string the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
subject string the subject line of the template, if provided - draft version
from_email string the default sender address for the template, if provided - draft version
from_name string the default sender from name for the template, if provided - draft version
text string the default text part of messages sent with the template, if provided - draft version
publish_name string the same as the template name - kept as a separate field for backwards compatibility
publish_code string the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
publish_subject string the subject line of the template, if provided
publish_from_email string the default sender address for the template, if provided
publish_from_name string the default sender from name for the template, if provided
publish_text string the default text part of messages sent with the template, if provided
published_at string the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
created_at string the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
updated_at string the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_Template The requested template does not exist
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/delete.json

Delete a template

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","name":"Example Template"}' 'https://mandrillapp.com/api/1.0/templates/delete.json'

Example Response

{"slug":"example-template","name":"Example Template","labels":["example-label"],"code":"<div mc:edit=\"editable\">editable content<\/div>","subject":"example subject","from_email":"from.email@example.com","from_name":"Example Name","text":"Example text","publish_name":"Example Template","publish_code":"<div mc:edit=\"editable\">different than draft content<\/div>","publish_subject":"example publish_subject","publish_from_email":"from.email.published@example.com","publish_from_name":"Example Published Name","publish_text":"Example published text","published_at":"2013-01-01 15:30:40","created_at":"2013-01-01 15:30:27","updated_at":"2013-01-01 15:30:49"}

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
name* string the immutable name of an existing template
Validation: required
Return Value
struct the template that was deleted
slug string the immutable unique code name of the template
name string the name of the template
labels array the list of labels applied to the template
labels[] string a single label
code string the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
subject string the subject line of the template, if provided - draft version
from_email string the default sender address for the template, if provided - draft version
from_name string the default sender from name for the template, if provided - draft version
text string the default text part of messages sent with the template, if provided - draft version
publish_name string the same as the template name - kept as a separate field for backwards compatibility
publish_code string the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
publish_subject string the subject line of the template, if provided
publish_from_email string the default sender address for the template, if provided
publish_from_name string the default sender from name for the template, if provided
publish_text string the default text part of messages sent with the template, if provided
published_at string the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
created_at string the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
updated_at string the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Unknown_Template The requested template does not exist
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/list.json

Return a list of all the templates available to this user

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","label":"example-label"}' 'https://mandrillapp.com/api/1.0/templates/list.json'

Example Response

[{"slug":"example-template","name":"Example Template","labels":["example-label"],"code":"<div mc:edit=\"editable\">editable content<\/div>","subject":"example subject","from_email":"from.email@example.com","from_name":"Example Name","text":"Example text","publish_name":"Example Template","publish_code":"<div mc:edit=\"editable\">different than draft content<\/div>","publish_subject":"example publish_subject","publish_from_email":"from.email.published@example.com","publish_from_name":"Example Published Name","publish_text":"Example published text","published_at":"2013-01-01 15:30:40","created_at":"2013-01-01 15:30:27","updated_at":"2013-01-01 15:30:49"}]

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
label string an optional label to filter the templates
Return Value
array an array of structs with information about each template
return[] struct the information on each template in the account
slug string the immutable unique code name of the template
name string the name of the template
labels array the list of labels applied to the template
labels[] string a single label
code string the full HTML code of the template, with mc:edit attributes marking the editable elements - draft version
subject string the subject line of the template, if provided - draft version
from_email string the default sender address for the template, if provided - draft version
from_name string the default sender from name for the template, if provided - draft version
text string the default text part of messages sent with the template, if provided - draft version
publish_name string the same as the template name - kept as a separate field for backwards compatibility
publish_code string the full HTML code of the template, with mc:edit attributes marking the editable elements that are available as published, if it has been published
publish_subject string the subject line of the template, if provided
publish_from_email string the default sender address for the template, if provided
publish_from_name string the default sender from name for the template, if provided
publish_text string the default text part of messages sent with the template, if provided
published_at string the date and time the template was last published as a UTC string in YYYY-MM-DD HH:MM:SS format, or null if it has not been published
created_at string the date and time the template was first created as a UTC string in YYYY-MM-DD HH:MM:SS format
updated_at string the date and time the template was last modified as a UTC string in YYYY-MM-DD HH:MM:SS format
Errors
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/time-series.json

Return the recent history (hourly stats for the last 30 days) for a template

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","name":"Example Template"}' 'https://mandrillapp.com/api/1.0/templates/time-series.json'

Example Response

[{"time":"2013-01-01 15:00:00","sent":42,"hard_bounces":42,"soft_bounces":42,"rejects":42,"complaints":42,"opens":42,"unique_opens":42,"clicks":42,"unique_clicks":42}]

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
name* string the name of an existing template
Validation: required
Return Value
array the array of history information
return[] struct the stats for a single hour
time string the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
sent integer the number of emails that were sent during the hour
hard_bounces integer the number of emails that hard bounced during the hour
soft_bounces integer the number of emails that soft bounced during the hour
rejects integer the number of emails that were rejected during the hour
complaints integer the number of spam complaints received during the hour
opens integer the number of emails opened during the hour
unique_opens integer the number of unique opens generated by messages sent during the hour
clicks integer the number of tracked URLs clicked during the hour
unique_clicks integer the number of unique clicks generated by messages sent during the hour
Errors
Unknown_Template The requested template does not exist
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.

/templates/render.json

Inject content and optionally merge fields into a template, returning the HTML that results

Example Request

curl -A 'Mandrill-Curl/1.0' -d '{"key":"example key","template_name":"Example Template","template_content":[{"name":"editable","content":"<div>content to inject *|MERGE1|*<\/div>"}],"merge_vars":[{"name":"merge1","content":"merge1 content"}]}' 'https://mandrillapp.com/api/1.0/templates/render.json'

Example Response

{"html":"<p><div>content to inject merge1 content<\/div><\/p>"}

Example Error Response

{"status":"error","code":-1,"name":"Invalid_Key","message":"Invalid API key"}
Parameters
key* string a valid API key
template_name* string the immutable name of a template that exists in the user's account
Validation: required
template_content* array an array of template content to render. Each item in the array should be a struct with two keys - name: the name of the content block to set the content for, and content: the actual content to put into the block
template_content[] struct the injection of a single piece of content into a single editable region
name* string the name of the mc:edit editable region to inject into
required
content* string the content to inject
required
merge_vars array optional merge variables to use for injecting merge field content. If this is not provided, no merge fields will be replaced.
merge_vars[] struct a single merge variable
name string the merge variable's name. Merge variable names are case-insensitive and may not start with _
content string the merge variable's content
Return Value
struct the result of rendering the given template with the content and merge field values injected
html string the rendered HTML as a string
Errors
Unknown_Template The requested template does not exist
Invalid_Key The provided API key is not a valid Mandrill API key
ValidationError The parameters passed to the API call are invalid or not provided when required
GeneralError An unexpected error occurred processing the request. Mandrill developers will be notified.