Templates

Templates are a way to store and edit email content. Instead of passing inline content to a Transmission request, a template can be set to provide the content. All email content in a template (from, headers, text, html, and amp_html) supports the template language for personalized emails.

Drafts & Published versions

Templates can have both a draft and a published version. Transmissions send the published version by default. This allows you to work on an upcoming version of the content while continuing to send the last published version. Once ready, publish the draft to the start sending the new version without needing to change the transmission request. If needed, it's also possible to update the published version of a template directly, without affecting the draft version.

Template Object

Example

{
  "id": "onboarding-email",
  "name": "Onboarding email",
  "description": "First email sent on sign-up",
  "content": {
    "html": "<p>Please confirm your email by clicking <a href=\"{{ link }}\">this link</a></p>",
    "text": "Please confirm your email by clicking this link: {{ link }}",
    "from": "{{ friendly_from }} <team@ourdomain.com>",
    "subject": "Welcome!"
  },
  "published": true,
  "has_draft": true,
  "has_published": true,
  "last_update_time": "2018-07-03T23:41:07+00:00",
  "last_use": "2018-07-02T18:48:18+00:00",
  "shared_with_subaccounts": false,
  "options": {
    "transactional": true
  }
}

Attributes

id string

Unique alphanumeric ID.

name string

Display name.

description string

Description of the template.

content object

Content that will be used to construct an email. The template language is supported in all content attributes.

published boolean

Whether the template is published or is a draft version. A template cannot be changed from published to draft.

options object

Object containing template options. All template options can be overwritten in a transmission's options.

has_draft boolean

Whether the template has a draft version.

has_published boolean

Whether the template has a published version.

last_update_time string

The last date this template was updated.

last_use string

The last date any version of this template (draft or published) was used for generating an email. Only present if template has been used.

shared_with_subaccounts boolean

Whether this template can be used by subaccounts. Only present on templates that belong to a primary account.

subaccount_id number

Subaccount the template belongs to. Only present on templates that belong to a subaccount.

Header Notes

Headers such as Content-Type and Content-Transfer-Encoding are not allowed, as they are auto-generated upon construction of the email.
The To header should not be specified, since it is generated from each recipient's address field.
Each header value is expected in the UTF-8 charset without RFC2047 encoding.
The template language is supported in headers.

Error Object

On request failure, an errors array will be returned along with HTTP 4xx or 5xx. To help debug content issues, templates errors are more detailed than usual. Each error is described in a object with the following attributes:

Example

{
  "errors": [
    {
      "message": "substitution language syntax error in template content",
      "code": "3000",
      "description": "Error while compiling part text: line 4: syntax error near 'age'",
      "part": "html",
      "line": 4
    }
  ]
}

Attributes

message string

Explains the type of error

code string

Identifies the type of error

description string

Explanation of error

part enum

Identifies the content section where the error occurred

Possible Values: text, html, amp_html, Header:Subject

line number

Identifies the line number within the MIME part identified by the part attribute

Request

POST /api/v1/templates

{
  "id": "summer_sale",
  "name": "Summer Sale!",
  "published": true,
  "description": "Template for a Summer Sale!",
  "shared_with_subaccounts": false,
  "options": {
    "open_tracking": false,
    "click_tracking": true
  },
  "content": {
    "from": {
      "email": "marketing@bounces.company.example",
      "name": "Example Company Marketing"
    },
    "subject": "Summer deals for {{name}}",
    "reply_to": "Summer deals <summer_deals@company.example>",
    "text": "Check out these deals {{name}}!",
    "html": "<b>Check out these deals {{name}}!</b>",
    "headers": {
      "X-Example-Header": "Summer2014"
    }
  }
}

Response

{
  "results": {
    "id": "summer_sale"
  }
}

{
  "errors": [
    {
      "part": "text",
      "description": "Error while compiling part text: line 4: syntax error near 'age'",
      "line": 4,
      "code": "3000",
      "message": "substitution language syntax error in template content"
    }
  ]
}

Create a Template

POST/api/v1/templates

Templates are created as drafts.

Request Body

id string

Unique alphanumeric ID used to reference the template. At a minimum, id or name is required upon creation. It is auto-generated if not provided. Maximum length - 64 bytes

name string

Editable display name. At a minimum, id or name is required upon creation. Does not have to be unique. Maximum length - 1024 bytes

description string

Description of the template. Maximum length - 1024 bytes

content object required

Content that will be used to construct an email. The template language is supported in all content attributes. Maximum length - 5 MB

options object

Object containing template options. All template options can be overwritten in a transmission's options.

shared_with_subaccounts boolean

Whether this template can be used by subaccounts. Can only be set if the template belongs to the primary account.

Request

GET /api/v1/templates/11714265276872?draft=true

Response

{
  "results": {
    "id": "summer_sale",
    "name": "Summer Sale!",
    "description": "",
    "has_draft": true,
    "has_published": true,
    "published": false,
    "shared_with_subaccounts": false,
    "last_update_time": "2014-05-22T15:12:59+00:00",
    "last_use": "2014-06-02T08:15:30+00:00",
    "options": {
      "open_tracking": false,
      "click_tracking": true,
      "transactional": false
    },
    "content": {
      "from": {
        "email": "marketing@bounces.company.example",
        "name": "Example Company Marketing"
      },
      "subject": "Summer deals for {{name}}",
      "reply_to": "Summer deals <summer_deals@company.example>",
      "text": "Check out these deals {{name}}!",
      "html": "<b>Check out these deals {{name}}!</b>",
      "headers": {
        "X-Example-Header": "Summer2014"
      }
    }
  }
}

Retrieve a Template

GET/api/v1/templates/{id}{?draft}

Parameters

id string required

Case sensitive.

draft boolean

If true, returns the draft template. If false, returns the published template.

Use the draft query parameter to specify the draft or published version of the template.

Request: Update

PUT /api/v1/templates/11714265276872

{
  "options": {
    "open_tracking": true
  },
  "name": "A new name!",
  "shared_with_subaccounts": true,
  "content": {
    "from": {
      "email": "marketing@bounces.company.example",
      "name": "Example Company Marketing"
    },
    "subject": "Updated Summer deals for {{name}}",
    "reply_to": "Summer deals <summer_deals@company.example>",
    "text": "Updated: Check out these deals {{name}}!",
    "html": "<b>Updated: Check out these deals {{name}}!</b>"
  }
}

Response

// Empty response body

Update a Draft

PUT/api/v1/templates/{id}

Parameters

id string required

Case sensitive.

Updates the draft version of a template.

If a content object is provided in the request body, it must contain all relevant content fields whether they are being changed or not. The new content will completely overwrite the existing content.

Request Body

name string

Template name. Does not have to be unique. Maximum length - 1024 bytes

description string

Description of the template. Maximum length - 1024 bytes

content object

Content that will be used to construct an email. The template language is supported in all content attributes. Maximum length - 5 MB

options object

Object containing template options. All template options can be overwritten in a transmission's options.

shared_with_subaccounts boolean

Whether this template can be used by subaccounts. Can only be set if the template belongs to the primary account. Updating this will update both the published and draft versions.

Request

PUT /api/v1/templates/11714265276872

{
  "published": true
}

Response

// Empty response body

Publish a Draft

PUT/api/v1/templates/{id}

Parameters

id string required

Uses the draft version to create a new published version.

Request Body

published boolean required

Set to true to publish the draft version.

Request

PUT /api/v1/templates/11714265276872?update_published=true

{
  "options": {
    "open_tracking": true
  },
  "name": "A new name!",
  "shared_with_subaccounts": true,
  "content": {
    "from": {
      "email": "marketing@bounces.company.example",
      "name": "Example Company Marketing"
    },
    "subject": "Updated Summer deals for {{name}}",
    "reply_to": "Summer deals <summer_deals@company.example>",
    "text": "Updated: Check out these deals {{name}}!",
    "html": "<b>Updated: Check out these deals {{name}}!</b>"
  }
}

Response

// Empty response body

Update a Published Template

PUT/api/v1/templates/{id}{?update_published}

Parameters

id string required

Case sensitive.

update_published boolean

Set to true to overwrite the existing published template.

An existing published version can be overwritten directly by setting the update_published query parameter to true. If the query param is not passed or set to false, it will result in an update to the draft version.

If a content object is provided in the update request, it must contain all relevant content fields whether they are being changed or not. The new content will completely overwrite the existing content.

Request Body

name string

Template name. Does not have to be unique. Maximum length - 1024 bytes

description string

Description of the template. Maximum length - 1024 bytes

content object

Content that will be used to construct an email. The template language is supported in all content attributes. Maximum length - 5 MB

options object

Object containing template options. All template options can be overwritten in a transmission's options.

shared_with_subaccounts boolean

Whether this template can be used by subaccounts. Can only be set if the template belongs to the primary account. Updating this will update both the published and draft versions.

Request

POST /api/v1/templates/11714265276872/preview?draft=true

{
  "substitution_data": {
    "name": "Natalie",
    "age": 35,
    "member": true
  }
}

Response

{
  "results": {
    "from": {
      "email": "marketing@bounces.company.example",
      "name": "Example Company Marketing"
    },
    "subject": "Summer deals for Natalie",
    "reply_to": "Summer deals <summer_deals@company.example>",
    "text": "Check out these deals Natalie!",
    "html": "<b>Check out these deals Natalie!</b>",
    "headers": {
      "X-Example-Header": "Summer2018"
    }
  }
}

Preview a Template

POST/api/v1/templates/{id}/preview{?draft}

Parameters

id string required

Case sensitive.

draft boolean

If true, previews the draft template. If false, previews the published template.

The template's content will be expanded using the substitution data provided and returned in the response. Use the draft query parameter to specify a draft or published version.

See Template Language for more information.

Request Body

substitution_data object

Data passed to the template engine.

Request

DELETE /api/v1/templates/11714265276872

Response

{}

{
  "errors": [
    {
      "message": "resource conflict",
      "code": "1602",
      "description": "Template is in use by msg generation"
    }
  ]
}

Delete a Template

DELETE/api/v1/templates/{id}

Parameters

id string required

Case sensitive.

Deletes both published and draft versions of a template.

If a transmission uses a template, the template cannot be deleted if the transmission is submitted or generating.

Request

GET /api/v1/templates?draft=true&shared_with_subaccounts=true

Response

  {
      "results": [
          {
              "id": "summer_sale",
              "name": "Summer Sale!",
              "published": false,
              "description": "",
              "has_draft": true,
              "has_published": true,
              "last_update_time": "2017-08-11T12:12:12+00:00",
              "shared_with_subaccount": true
          },
          {
              "id": "daily",
              "name": "daily",
              "published": false,
              "description": "Daily roundup email.",
              "has_draft": true,
              "has_published": true,
              "last_use": "2018-05-08T14:49:03+00:00"
              "last_update_time": "2018-02-10T14:15:16+00:00",
              "shared_with_subaccount": true
          }
      ]
  }

List all Templates

GET/api/v1/templates{?draft,shared_with_subaccounts}

Parameters

draft boolean

If true, returns the draft templates. If false, returns the published templates. When not provided, returns the most recently edited templates (draft or published).

shared_with_subaccounts boolean

If true, returns only shared templates. If false, returns only non-shared templates.

Returns an array containing up to your first 50,000 templates.

Request: Create RFC822

POST /api/v1/templates

{
  "id": "another_summer_sale",
  "name": "Summer Sale!",
  "published": true,
  "options": {
    "open_tracking": false,
    "click_tracking": true
  },
  "content": {
    "email_rfc822": "Content-Type: text/plain\nFrom: Example Company Marketing <marketing@bounces.company.example>\nReply-To:Summer deals <summer_deals@company.example>\nX-Example-Header: Summer2014\nSubject: Summer deals for {{name}}\n\nCheck out these deals {{name}}!"
  }
}

Response

{
  "results": {
    "id": "another_summer_sale"
  }
}

Create an RFC 822 Template

POST/api/v1/templates

Instead of the standard attributes, the content object may contain a single email_rfc822 attribute. email_rfc822 is mutually exclusive with all other content attributes.

RFC 822 Content

email_rfc822 string

Pre-built message with the format as described by the message/rfc822 Content-Type.

Substitutions will be applied in the top-level headers and the first non-attachment text/plain, text/html, and text/x-amp-html MIME parts only.
If text/x-amp-html is used, it must be a descendant of multipart/alternative, alongside at least one other text/html or text/plain MIME part.
Lone LFs and lone CRs are allowed. SparkPost converts line endings to CRLF where necessary.
It should NOT be dot stuffed. SparkPost dot stuffs before sending the email.
It should NOT contain the SMTP terminator \r\n.\r\n. SparkPost adds this terminator.

Request

POST /api/v1/utils/content-previewer

{
  "substitution_data": {
    "name": "Natalie",
    "age": 35,
    "member": true
  },
  "content": {
    "from": "sandbox@sparkpostbox.com",
    "subject": "Summer deals for {{name}}",
    "html": "<b>Check out these deals {{name}}!</b>"
  }
}

Response

{
  "results": {
    "subject": "Summer deals for Natalie",
    "html": "<b>Check out these deals Natalie!</b>"
  }
}

Preview an inline Template

POST/api/v1/utils/content-previewer

Requests to this endpoint must include the "substitution_data" and "content" fields. The content will be expanded using the substitution data and returned in the response.

See the Templates API section for the definition of the content object.

See Template Language for more information.

Data Structure
- substitution_data (object) - Data passed to the template engine.
- content (object) - Inline template content fields.