Campaign Templates API

Table of Contents
Overview
Campaign Template Attributes
Get a List of Campaign Templates
- Response
- Example
Get Campaign Template Details
- Response
- Example
Create a New Campaign Template
- Payload
- Response
- Example
Update an Existing Campaign Template
- Payload
- Response
- Example

Overview

This API provides a way to manage your Campaign Templates.

Campaign Template Attributes

id
integer
/
read-only

An automatically generated unique identifier for this template.

name
string

The name of the campaign template.

mailing_list_id
integer

The id of the mailing list to which this template belongs.

mailing_list_name
string

The name of the mailing list to which this template belongs.

content_subject
string

Deprecated: The subject of the email.

For split-test campaigns, this field will contain the data on the first content by its ID value.

email_format
string

Deprecated: Email format to use when delivering a campaign from this template.

Valid formats include html, text, and both.
For split-test campaigns, this field will contain the data on the first content by its ID value.

content_html
string

Deprecated: If format is html or both, this is the HTML portion of the email.

For split-test campaigns, this field will contain the data on the first content by its ID value.

content_text
string

Deprecated: If format is text or both, this is the plaintext portion of the email.

For split-test campaigns, this field will contain the data on the first content by its ID value.

segmentation_criteria_id
integer

The id of the segment to use when delivering a campaign from this template.

segmentation_criteria_name
string

The name of the segment, if it is a stored segment.

segmentation_criteria_remote_sql
string

The SQL to use when querying the remote database for a campaign from this template. This only applies to Remote Lists.

contents
array of hashes

id integer	The ID for this content record.
name string	String identifier for this content.
subject string	The subject of the email.
format string	Email format to use when delivering a campaign from this template. Valid formats include `html`, `text`, and `both`.
html string	If format is `html` or `both`, this is the HTML portion of the email.
text string	If format is `text` or `both`, this is the plaintext portion of the email.

dispatch_attributes
array of hashes

Inline object containing delivery settings of the Template;

Comes from the server only if delivery settings of the Template are defined.

This key is named dispatch_attributes when creating or updating records, dispatch in responses.

state string	The state of delivery; Can be one of: `idle`, `scheduled`, `sending`, `finished`, `failed`, `cancelled`.
virtual_mta_id integer	The id of a Virtual MTA explicitly assigned to the Template; Will come blank if Template is about to use general setting
virtual_mta_name string	The name of a Virtual MTA explicitly assigned to the Template
bounce_email_id string	The id of a Bounce Email explicitly assigned to the Template; Will come blank if Template is about to use general setting
bounce_email_name string	The Bounce Email explicitly assigned to the Template
url_domain_id integer	The id of an URL domain explicitly assigned to the Template
url_domain_name string	The URL domain explicitly assigned to the Template
seed_list_id integer	The id of a Seed List assigned to the Template
seed_list_name string	The name of the Seed List assigned to the Template
speed integer	Maximum throughput speed; `0` for unlimited throughput
track_opens boolean	Marks whether the Template will track openings stats
track_links boolean	Marks whether the Template will track clicks stats
paused boolean	Marks whether the Template has been paused
from_name string	Name to use in the `From` field
from_email string	Email to use in the `From` field
reply_to string	Email to use in the `Reply-To` header
begins_at string	Time to start delivery at
started_at string	Time when delivery actually started
autowinner_enabled boolean	The template is configured to use automatic winner selection.
autowinner_percentage string	The percentage that will be sent for the split-test portion of the template. This value is returned as a string to prevent floating-point conversion errors. You may send this value as an Integer, Float or String. Posting a value with more than 2 decimals will cause a validation error. Be careful because IEEE floating point can not exactly represent some decimal values. For example `94.85` is represented as `94.85000000000001` which will cause a validation error if used here. You may want to print to a string using two decimals of precision.
autowinner_delay_amount integer	The number of units of time that the template will wait before finishing after a split-test.
autowinner_delay_unit string	The unit used in calculating the delay duration.
autowinner_metric string	The metric used to decide the winner. See Automatic Winner Selection Metrics for more information.

Get a List of Campaign Templates

Campaign Templates on a mailing list:

GET /ga/api/v2/mailing_lists/:mailing_list_id/templates

Campaign Templates on the current user’s organization:

GET /ga/api/v2/templates

Response

The response will be a JSON array where each element contains the following keys.

id integer / read-only	An automatically generated unique identifier for this template.
name string	The name of the Campaign
mailing_list_id integer	The id of the mailing list to which this template belongs.
mailing_list_name string	The name of the mailing list to which this template belongs.

Example

GET /ga/api/v2/mailing_lists/9/templates

HTTP/1.1 200 OK

{
  "success": true,
  "data": [
    {
      "id": 40,
      "mailing_list_id": 9,
      "name": "Daily Update Template",
      "organization_id": 8,
      "segmentation_criteria_id": null,
      "mailing_list_name": "Monthly Subscribers"
    },
    {
      "id": 41,
      "mailing_list_id": 9,
      "name": "Monthly Update Template",
      "organization_id": 8,
      "segmentation_criteria_id": null,
      "mailing_list_name": "Monthly Subscribers"
    },
    {
      "id": 42,
      "mailing_list_id": 9,
      "name": "Random Update Template",
      "organization_id": 8,
      "segmentation_criteria_id": null,
      "mailing_list_name": "Monthly Subscribers"
    }
  ],
  "error_code": null,
  "error_message": null
}

Get Campaign Template Details

GET /ga/api/v2/templates/:template_id

Response

The response will contain details defined in the Campaign Template Attributes section of this document.

Example

GET /ga/api/v2/templates/46

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "archived": false,
    "content_determined": false,
    "created_at": "2017-05-09T19:21:23Z",
    "custom_dynamic_template_id": null,
    "id": 46,
    "mailing_list_id": 10,
    "name": "Daily Update Template",
    "organization_id": 9,
    "segmentation_criteria_id": null,
    "template": true,
    "updated_at": "2017-05-09T19:21:23Z",
    "mailing_list_name": "Monthly Subscribers",
    "organization_name": "News Co",
    "stat_summary": null,
    "content_stats": [

    ],
    "automatic_winner_selection": null,
    "campaign_contents": [

    ]
  },
  "error_code": null,
  "error_message": null
}

Create a New Campaign Template

POST /ga/api/v2/mailing_lists/:mailing_list_id/templates

Payload

The POST request should have a JSON document in its payload with at least keys that marked with bold in the following list:

campaign
hash
/
required

The content of this hash is described in the Campaign Template Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

A successful response will return the template record using the format described in the Campaign Template Attributes section of the API.

Example

POST /ga/api/v2/mailing_lists/11/templates

{
  "campaign": {
    "name": "New Template"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "archived": false,
    "content_determined": false,
    "created_at": "2017-05-09T19:21:23Z",
    "custom_dynamic_template_id": null,
    "id": 55,
    "mailing_list_id": 11,
    "name": "New Template",
    "organization_id": 10,
    "segmentation_criteria_id": null,
    "template": true,
    "updated_at": "2017-05-09T19:21:23Z",
    "mailing_list_name": "Monthly Subscribers",
    "organization_name": "News Co",
    "stat_summary": null,
    "content_stats": [

    ],
    "automatic_winner_selection": null,
    "campaign_contents": [

    ]
  },
  "error_code": null,
  "error_message": null
}

Update an Existing Campaign Template

PUT /ga/api/v2/templates/:template_id

Payload

campaign
hash
/
required

The content of this hash is described in the Campaign Template Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

A successful response will return the template record using the format described in the Campaign Template Attributes section of the API.

Example

PUT /ga/api/v2/templates/59

{
  "campaign": {
    "name": "Updated Template",
    "dispatch_attributes": {
      "speed": 150,
      "bounce_email_id": "5012@59912",
      "virtual_mta_id": 0,
      "url_domain_id": 1,
      "from_name": "From Example",
      "from_email": "[email protected]"
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "archived": false,
    "content_determined": false,
    "created_at": "2017-05-09T19:21:23Z",
    "custom_dynamic_template_id": null,
    "id": 59,
    "mailing_list_id": 12,
    "name": "Updated Template",
    "organization_id": 11,
    "segmentation_criteria_id": null,
    "template": true,
    "updated_at": "2017-05-09T19:21:23Z",
    "mailing_list_name": "Monthly Subscribers",
    "organization_name": "News Co",
    "stat_summary": null,
    "content_stats": [

    ],
    "automatic_winner_selection": null,
    "dispatch": {
      "autowinner_delay_amount": null,
      "autowinner_delay_unit": "minutes",
      "autowinner_enabled": false,
      "autowinner_metric": null,
      "autowinner_percentage": null,
      "begins_at": null,
      "finished_at": null,
      "from_email": "[email protected]",
      "from_name": "From Example",
      "paused": false,
      "reply_to": null,
      "sender_email": null,
      "speed": 150,
      "started_at": null,
      "state": "idle",
      "track_links": true,
      "track_opens": true,
      "url_domain_id": 1,
      "virtual_mta_id": 0,
      "state_description": "Step 1: Pending",
      "virtual_mta_name": "System Default Route",
      "virtual_mta_type": "default_route",
      "bounce_email_user_id": 5012,
      "bounce_email_domain_id": 59912,
      "bounce_email_email": "[email protected]",
      "url_domain_domain": "example.com",
      "seed_lists": [

      ],
      "special_sending_rule_id": null,
      "special_sending_rule_name": null,
      "seed_list_id": null,
      "seed_list_name": null
    },
    "campaign_contents": [

    ]
  },
  "error_code": null,
  "error_message": null
}