Templates API | Mandrill

/templates/add.json

Add a new template

Example Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_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"]
    result = mandrill.templates.add name, from_email, from_name, subject, code, text, publish, labels
        # {"published_at"=>"2013-01-01 15:30:40",
        #  "publish_name"=>"Example Template",
        #  "publish_from_email"=>"from.email.published@example.com",
        #  "publish_text"=>"Example published text",
        #  "name"=>"Example Template",
        #  "publish_code"=>
        #     "different than draft content",
        #  "subject"=>"example subject",
        #  "updated_at"=>"2013-01-01 15:30:49",
        #  "publish_from_name"=>"Example Published Name",
        #  "labels"=>["example-label"],
        #  "created_at"=>"2013-01-01 15:30:27",
        #  "text"=>"Example text",
        #  "publish_subject"=>"example publish_subject",
        #  "from_name"=>"Example Name",
        #  "code"=>"editable content",
        #  "slug"=>"example-template",
        #  "from_email"=>"from.email@example.com"}
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters

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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_KEY'
    name = "Example Template"
    result = mandrill.templates.info name
        # {"publish_text"=>"Example published text",
        #  "publish_from_email"=>"from.email.published@example.com",
        #  "code"=>"editable content",
        #  "publish_code"=>
        #     "different than draft content",
        #  "from_name"=>"Example Name",
        #  "publish_subject"=>"example publish_subject",
        #  "from_email"=>"from.email@example.com",
        #  "created_at"=>"2013-01-01 15:30:27",
        #  "published_at"=>"2013-01-01 15:30:40",
        #  "publish_from_name"=>"Example Published Name",
        #  "updated_at"=>"2013-01-01 15:30:49",
        #  "name"=>"Example Template",
        #  "publish_name"=>"Example Template",
        #  "labels"=>["example-label"],
        #  "slug"=>"example-template",
        #  "text"=>"Example text",
        #  "subject"=>"example subject"}
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters
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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_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"]
    result = mandrill.templates.update name, from_email, from_name, subject, code, text, publish, labels
        # {"subject"=>"example subject",
        #  "publish_from_name"=>"Example Published Name",
        #  "text"=>"Example text",
        #  "from_name"=>"Example Name",
        #  "from_email"=>"from.email@example.com",
        #  "created_at"=>"2013-01-01 15:30:27",
        #  "slug"=>"example-template",
        #  "code"=>"editable content",
        #  "updated_at"=>"2013-01-01 15:30:49",
        #  "published_at"=>"2013-01-01 15:30:40",
        #  "publish_name"=>"Example Template",
        #  "publish_subject"=>"example publish_subject",
        #  "publish_code"=>
        #     "different than draft content",
        #  "labels"=>["example-label"],
        #  "name"=>"Example Template",
        #  "publish_text"=>"Example published text",
        #  "publish_from_email"=>"from.email.published@example.com"}
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters

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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_KEY'
    name = "Example Template"
    result = mandrill.templates.publish name
        # {"from_name"=>"Example Name",
        #  "publish_from_name"=>"Example Published Name",
        #  "from_email"=>"from.email@example.com",
        #  "labels"=>["example-label"],
        #  "created_at"=>"2013-01-01 15:30:27",
        #  "text"=>"Example text",
        #  "code"=>"editable content",
        #  "slug"=>"example-template",
        #  "updated_at"=>"2013-01-01 15:30:49",
        #  "published_at"=>"2013-01-01 15:30:40",
        #  "publish_subject"=>"example publish_subject",
        #  "publish_code"=>
        #     "different than draft content",
        #  "publish_from_email"=>"from.email.published@example.com",
        #  "publish_name"=>"Example Template",
        #  "publish_text"=>"Example published text",
        #  "subject"=>"example subject",
        #  "name"=>"Example Template"}
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters
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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_KEY'
    name = "Example Template"
    result = mandrill.templates.delete name
        # {"published_at"=>"2013-01-01 15:30:40",
        #  "publish_code"=>
        #     "different than draft content",
        #  "updated_at"=>"2013-01-01 15:30:49",
        #  "publish_from_email"=>"from.email.published@example.com",
        #  "from_name"=>"Example Name",
        #  "name"=>"Example Template",
        #  "created_at"=>"2013-01-01 15:30:27",
        #  "from_email"=>"from.email@example.com",
        #  "slug"=>"example-template",
        #  "publish_from_name"=>"Example Published Name",
        #  "publish_name"=>"Example Template",
        #  "code"=>"editable content",
        #  "text"=>"Example text",
        #  "publish_text"=>"Example published text",
        #  "subject"=>"example subject",
        #  "labels"=>["example-label"],
        #  "publish_subject"=>"example publish_subject"}
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters
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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_KEY'
    label = "example-label"
    result = mandrill.templates.list label
        # [{"publish_name"=>"Example Template",
        #     "from_name"=>"Example Name",
        #     "publish_code"=>
        #      "different than draft content",
        #     "slug"=>"example-template",
        #     "publish_text"=>"Example published text",
        #     "text"=>"Example text",
        #     "publish_from_email"=>"from.email.published@example.com",
        #     "subject"=>"example subject",
        #     "updated_at"=>"2013-01-01 15:30:49",
        #     "published_at"=>"2013-01-01 15:30:40",
        #     "from_email"=>"from.email@example.com",
        #     "publish_from_name"=>"Example Published Name",
        #     "created_at"=>"2013-01-01 15:30:27",
        #     "publish_subject"=>"example publish_subject",
        #     "code"=>"editable content",
        #     "labels"=>["example-label"],
        #     "name"=>"Example Template"}]
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters
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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_KEY'
    name = "Example Template"
    result = mandrill.templates.time_series name
        # [{"rejects"=>42,
        #     "sent"=>42,
        #     "unique_clicks"=>42,
        #     "complaints"=>42,
        #     "hard_bounces"=>42,
        #     "unique_opens"=>42,
        #     "soft_bounces"=>42,
        #     "time"=>"2013-01-01 15:00:00",
        #     "clicks"=>42,
        #     "opens"=>42}]
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters
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 Call


begin
    mandrill = Mandrill::API.new 'YOUR_API_KEY'
    template_name = "Example Template"
    template_content = [{"content"=>"<div>content to inject *|MERGE1|*</div>", "name"=>"editable"}]
    merge_vars = [{"content"=>"merge1 content", "name"=>"merge1"}]
    result = mandrill.templates.render template_name, template_content, merge_vars
        # {"html"=>"
content to inject merge1 content
"}
    
rescue Mandrill::Error => e
    # Mandrill errors are thrown as exceptions
    puts "A mandrill error occurred: #{e.class} - #{e.message}"
    # A mandrill error occurred: Mandrill::InvalidKeyError - Invalid API key
    raise
end

Parameters

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.

Mandrill by Mailchimp

Templates Calls

/templates/add.json

Example Call

/templates/info.json

Example Call

/templates/update.json

Example Call

/templates/publish.json

Example Call

/templates/delete.json

Example Call

/templates/list.json

Example Call

/templates/time-series.json

Example Call

/templates/render.json

Example Call