Campaign Templates API

Campaign Templates API

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 the “Automatic Winner Selection Metrics” table 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": "[email protected]",
      "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
}
 "Bounce Emails API"
"Campaigns API"