Campaigns API

Table of Contents
Get a List of Campaigns
Get Campaign Details
Create a New Campaign
Update an Existing Campaign
Pause a Campaign
Resume a Campaign
Get Campaign Per-Link Statistics
Estimate Number of Recipients in Campaign
- URL
- Response

Get a List of Campaigns

Get a list of the basic details of all campaigns of a particular mailing list.

URL

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

Request Parameters

started_at__start
timestamp

A UNIX integer timestamp or ISO-8601 datetime string representing the earliest started_at time to include.

started_at__end
timestamp

A UNIX integer timestamp or ISO-8601 datetime string representing the latest started_at time to include.

state
string

The campaign state(s) by which to filter the list of campaigns returned.

Can be one (or more, comma delimited) of: idle, scheduled, sending, finished, failed, cancelled.

The started_at__start and started_at__end parameters allow you to filter the results returned by this API. Providing either of these keys will result in only sending, finished, cancelled, or failed campaigns to be included in the results.

Response

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

id
integer

The campaign’s id.

mailing_list_id
integer

The id of the mailing list the campaign belongs to.

name
string

The name of the campaign.

organization_id
integer

The id of the organization the campaign belongs to.

segmentation_criteria_id
integer

The id of the segmentation criteria used by the campaign.

mailing_list_name
string

The name of the mailing list the campaign belongs to.

dispatch
hash

An inline object containing delivery settings of the campaign. It comes from the server only if delivery settings of the campaign are defined.

begins_at DateTime	Time to start delivery at.
finished_at DateTime	Time when delivery has finished.
paused boolean	Marks whether the campaign has been paused.
started_at DateTime	Time when delivery actually started.
state string	The state of delivery; Can be one of: `idle`, `scheduled`, `sending`, `finished`, `failed`, `cancelled`.
state_description string	Localized textual description of the state. Example: `"Step 2: Scheduled"`.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

> GET /ga/api/v2/mailing_lists/1/campaigns HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1Yzg4M2YzMzA5ZjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: greenarrow-studio.dev
> Accept: */*
>
{  "name": "My New Campaign"  "mailing_list_id": }< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< Set-Cookie: _session_id=458055a23f26f844e74f8cd7300f6445; path=/; HttpOnly
< X-Request-Id: f6e40d578ed1d9c418cca45e1b7fe532
< X-Runtime: 0.025540
< Connection: close

{
  "error_message" : null,
  "data" : [
    {
      "id" : 1,
      "content_html" : "",
      "stats" : null,
      "segmentation_criteria_id" : null,
      "created_at" : "2013-08-24T08:23:34Z",
      "organization_id" : 1,
      "mailing_list_name" : "test",
      "archived" : false,
      "content_determined" : true,
      "mailing_list_id" : 1,
      "content_subject" : "asdfadsf",
      "email_format" : "html",
      "content_text" : "",
      "updated_at" : "2013-08-26T11:37:45Z",
      "organization_name" : "System Organization",
      "name" : "test 1"
    }
  ]
}

Get Campaign Details

Get details of particular campaign belonging to a particular mailing list.

URL

GET /ga/api/v2/campaigns/:campaign_id

URL (Get campaign details by Stat ID Instead of Campaign ID)

GET /ga/api/v2/campaigns/by_stat/:stat_id

Request Parameters

You may provide an extra parameter include_engine_sendid=1 in the request URL. If this parameter is supplied, the response will include a engine_sendid string value. Use this sendid value in interacting with GreenArrow Engine’s API.

Response

name
string

The name of the campaign.

mailing_list_id
integer

The id of the mailing list this campaign belongs to.

name
string

The name of the mailing list this campaign belongs to.

x_campaign_id
string

The value of the X-CampaignID header included in messages from this campaign, with the s4: prefix removed. This value can be passed to the GreenArrow Monitor API as customer_defined_campaign_id.

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 this campaign. 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 this campaign.

segmentation_criteria_name
string

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

The SQL to use when querying the remote database for this campaign. 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 this campaign. 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
hash

state
string

The state of delivery; Can be one of: idle, scheduled, sending, finished, failed, cancelled

state_description
string

Localized textual description of the state.

virtual_mta_id
integer

The id of a Virtual MTA explicitly assigned to the campaign.

virtual_mta_name
string

The name of a Virtual MTA explicitly assigned to the campaign.

bounce_email_id
string

The id of a Bounce Email explicitly assigned to the campaign.

bounce_email_name
string

The Bounce Email explicitly assigned to the campaign.

url_domain_id
integer

The id of an URL domain explicitly assigned to the campaign.

url_domain_name
string

The URL domain explicitly assigned to the campaign.

seed_list_id
integer

Deprecated: The id of the first seed list assigned to the campaign, ordered by id. Use seed_lists instead.

seed_list_name
string

Deprecated: The name of the first seed list assigned to the campaign, ordered by id. Use seed_lists instead.

seed_lists
array of hashes

id integer	The id of a seed list used by this campaign.
name string	The name of a seed list used by this campaign.

speed
integer

Maximum throughput speed; 0 for unlimited throughput.

track_opens
boolean

Marks whether the campaign will track openings stats.

track_links
boolean

Marks whether the campaign will track clicks stats.

paused
boolean

Marks whether the campaign 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 field.

sender_email
string

Email to use in the Sender field.

begins_at
string

Time to start delivery at. If this value is specified and the campaign has a segment, content, and delivery settings — the campaign will be marked as scheduled and sending will begin at the requested time. If one of those sections are missing or this value is blank, the campaign will remain in an “idle” state.

If the requested time is more than 2 hours in the past, then an error will be returned. If the requested time is in the last 2 hours, then the current time will be used.

started_at
string

The time at which the campaign started sending. This will be null if the campaign has not yet started sending.

finished_at
string

The time at which the campaign finished sending. This will be null if the campaign has not yet finished sending.

autowinner_enabled
boolean

The campaign is configured to use automatic winner selection. For automatic winner selection to be used, this must be enabled and the campaign must have more than one content.

autowinner_percentage
string

The percentage that will be sent for the split-test portion of the campaign. This value is returned as a string to prevent floating-point conversion errors.

autowinner_delay_amount
integer

The number of units of time that the campaign will wait before finishing after a split-test.

autowinner_delay_unit
string

The unit used in calculating the delay duration. This may be minutes, hours, or days.

autowinner_metric
string

The metric used to decide the winner. See Automatic Winner Selection Metrics for more information.

special_sending_rule_id
integer

The id of the Special Sending Rule used for this campaign. Special Sending Rules may only be used on the System Organization. See note (4) below.

special_sending_rule_name
string

The name of the Special Sending Rule used for this campaign. See note (4) below.

stat_summary
hash

sent_text
integer

Number of recipients that were sent a text-only message.

sent_html
integer

Number of recipients that were sent a html-only message.

sent_multipart
integer

Number of recipients that were sent a multipart message.

messages_sent
integer

Total number of recipients, as shown in the Studio Statistics page. Suppressed addresses and seed lists addresses are not included.

messages_html
integer

Number of recipients that received either an HTML or multipart message.

messages_text
integer

Number of recipients that received a text-only message.

bounces_total
integer

Total number of bounces received.

bounces_unique
integer

Unique (by subscriber) bounces received.

bounces_unique_hard
integer

Number of unique (by subscriber) bounces where bounce_type is hard.

bounces_unique_soft
integer

Number of unique (by subscriber) bounces where bounce_type is soft.

bounces_unique_other
integer

Number of unique (by subscriber) bounces where bounce_type is other.

bounces_unique_local
integer

Number of unique (by subscriber) bounces that were local.

bounces_unique_remote
integer

Number of unique (by subscriber) bounces that were remote.

bounces_status_updated
integer

Number of recipients where status was updated to status ‘bounce’ (See 1 below).

bounces_unique_by_code
hash

Number of unique (by subscriber) bounces for each bounce code. The keys in the included hash are the bounce code.

bounced
integer

Deprecated: Unique (by subscriber) bounces received. This is just another name for bounces_unique.

duplicate_bounces
integer

Number of non-unique bounces.

unbounced
integer

Number of messages that were sent that have not bounced.

bounce_rate
float

Floating point value indicating the unique bounce rate for this campaign. This value ranges from 0.0 to 1.0.

bounce_rate_hard
float

The ratio of the unique bounces that were hard bounces. This value ranges from 0.0 to 1.0.

bounce_rate_soft
float

The ratio of the unique bounces that were soft bounces. This value ranges from 0.0 to 1.0.

bounce_rate_other
float

The ratio of the unique bounces that were other bounces. This value ranges from 0.0 to 1.0.

bounce_local_rate
float

The ratio of the unique bounces that were local bounces. This value ranges from 0.0 to 1.0.

clicks_total
integer

Number of total clicks.

clicks_unique
integer

Number of unique clicks (unique by subscriber).

clicks_unique_by_link
integer

Deprecated: Number of unique clicks (unique by subscriber/link) – this value does not carry much meaning – see the Links endpoint below.

duplicate_clicks
integer

Number of non-unique clicks.

click_rate
float

The ratio of messages that were accepted and have been clicked. This value ranges from 0.0 to 1.0

click_to_open_rate
float

The ratio of messages that were opened that have been clicked. This value ranges from 0.0 to 1.0

unclicked
integer

Number of messages that were accepted by the remote server but have not been clicked.

opens_total
integer

Number of total opens

opens_unique
integer

Number of unique opens (unique by subscriber)

open_rate
float

Ratio of messages that were accepted that have been opened. This value ranges from 0.0 to 1.0

open_ratio
float

Average number of times each opened message has been opened (opens_total / opens_unique). This value ranges from 0.0 to 1.0

unopened
integer

Number of messages that were accepted and have not been opened.

duplicate_opens
integer

Number of non-unique opens.

scomps_total
integer

Number of spam complaints

scomps_unique
integer

Number of unique spam complaints (unique by subscriber).

scomps_status_updated
integer

Number of recipients where the status was updated to status scomp (See 1 below).

duplicate_scomps
integer

Number of non-unique spam complaints.

scomp_rate
float

The ratio of messages that were accepted and complained. This value ranges from 0.0 to 1.0.

We recommend using this statistic with great caution. Please read this article on why using a per-ISP complaint ratio is often better: https://www.greenarrowemail.com/blog/the-most-misunderstood-statistic-in-email-delivery

unsubs_total
integer

Number of total unsubscribes

unsubs_unique
integer

Number of unique unsubscribes (unique by subscriber)

unsubs_status_updated
integer

Number of recipients where the status was updated to status unsubscribed (See 1 below).

duplicate_unsubs
integer

Number of non-unique unsubscribes.

unsub_rate
float

The ratio of messages that were accepted and unsubscribed. This value ranges from 0.0 to 1.0

skips_error
integer

Number of messages that were skipped due to a Special Sending Rule error.

skips_request
integer

Number of messages that were skipped due to a Special Sending Rule request.

total_messages
integer

Total number of messages injected for this campaign. This is the number of messages GreenArrow Studio injected, including messages to addresses in seed lists. Suppressed addresses are not included in this count.

total_success
integer

Number of messages that were successfully delivered to the remote server.

total_failure
integer

Number of messages ended due to SMTP conversation failures.

total_failure_toolong
integer

Number of messages ended due to being in the queue too long.

accepted
integer

Total number of messages that were accepted by the remote server.

accepted_rate
float

Ratio of messages that were attempted and accepted (accepted / messages_sent). This value ranges from 0.0 to 1.0

in_queue
integer

Number of messages that are currently in GreenArrow Engine’s delivery queue.

in_queue_rate
float

Ratio of the total number of messages that have been handed off to GreenArrow Engine and are still in queue. This value ranges from 0.0 to 1.0

max_unique_activities
integer

The max value of opens_unique, clicks_unique, unsubs_unique, and scomps_unique.

stat_id
integer

An internal database identifier for this campaign’s statistics.

privacy_protection

These are statistics broken down between subscribers that used privacy protection features (such as iCloud+ Private Relay or Mail Privacy Protection) and those that did not.

all_subscribers

Statistics for all subscribers, regardless of privacy protection status.

opens_unique integer	The number of unique opens.
opens_unique_rate float	Ratio of messages that were accepted that have been opened. This value ranges from `0.0` to `1.0`.
opens_total integer	The total number of opens.
privacy_opens_unique integer	The number of unique opens using privacy features.
privacy_opens_unique_rate float	Ratio of messages that were accepted that have been opened using privacy features. This value ranges from `0.0` to `1.0`.
privacy_opens_total integer	The number of total opens using privacy features.
nonprivacy_opens_unique integer	The number of unique opens not using privacy features.
nonprivacy_opens_unique_rate float	Ratio of messages that were accepted that have been opened not using privacy features. This value ranges from `0.0` to `1.0`.
nonprivacy_opens_total integer	The total number of opens not using privacy features.
subscriber_count integer	The total number of messages that were accepted.

privacy_subscribers

Statistics for subscribers detected to be using privacy features.

opens_unique integer	The number of unique opens.
privacy_opens_unique integer	The number of unique opens using privacy features.
privacy_opens_unique_rate float	Ratio of messages that were accepted that have been opened using privacy features. This value ranges from `0.0` to `1.0`.
privacy_opens_total integer	The total number of opens using privacy features.
nonprivacy_opens_unique integer	The number of unique opens not using privacy features. Ratio of messages that were accepted that have been opened not using privacy features. This value ranges from `0.0` to `1.0`.
nonprivacy_opens_unique_rate float	Ratio of messages that were accepted that have been opened not using privacy features. This value ranges from `0.0` to `1.0`.
nonprivacy_opens_total integer	The total number of opens not using privacy features.
subscriber_count integer	The total number of messages to subscribers where the message was opened by privacy features. This is equal to `privacy_subscribers.opens_unique`.

nonprivacy_subscribers

Statistics for subscribers not detected to be using privacy features.

opens_unique integer	The number of unique opens.
nonprivacy_opens_unique integer	The number of unique opens not using privacy features. Ratio of messages that were accepted that have been opened not using privacy features. This value ranges from `0.0` to `1.0`.
nonprivacy_opens_unique_rate float	Ratio of messages that were accepted that have been opened not using privacy features. This value ranges from `0.0` to `1.0`. This is the statistic that is closest to a traditional open rate, before privacy features became commonplace.
nonprivacy_opens_total integer	The total number of opens not using privacy features.
subscriber_count integer	The total number of messages to subscribers where the message was not opened by privacy features. This is equal to `all_subscribers.subscriber_count` minus `privacy_subscribers.subscriber_count`.

content_stats
array of hashes

content
hash

id integer	The id of this content.
name string	The name of this content.

stat_summary
hash

See the stat_summary section above for details on these fields.

automatic_winner_selection
hash

If this campaign does not use automatic winner selection, this value will be null.

state
string

The current state of automatic winner selection on this campaign. Possible values are: split_testing, decision_delay, finished

winning_content
hash

id integer	The id of this content.
name string	The name of this content.

snapshots
array of hashes

content
hash

id integer	The id of this content.
name string	The name of this content.
is_winner boolean	This content won in automatic winner selection.

snapshot
hash

See the stat_summary section above for details on these fields.

The status updated fields will always be 0 on Remote Lists.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

> GET /ga/api/campaigns/2 HTTP/1.1
> Authorization: Basic MTpkZDVjNmQ5NWM1Y2QyMDFmNDM1OTNhM2JlNjc4MmMyYjNhMGVhODhj
> Accept: application/json
> Content-Type: application/json

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "f622c5ef847b75998b7d1defc353e018"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=274d96960e9b54498ba8f8ff343b66fd; path=/; HttpOnly
< X-Request-Id: 23331bfb903702eceb2da74bad1e6660
< X-Runtime: 0.036800
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "data": {
    "archived": false,
    "content_determined": true,
    "created_at": "2015-05-05T14:35:28Z",
    "id": 2,
    "mailing_list_id": 1,
    "name": "Default Campaign (Duplicate #1)",
    "organization_id": 1,
    "segmentation_criteria_id": 2,
    "template": false,
    "updated_at": "2015-05-05T14:35:28Z",
    "mailing_list_name": "Default Mailing List",
    "organization_name": "System Organization",
    "stat_summary": {
      "sent_text": 0,
      "sent_html": 21,
      "sent_multipart": 0,
      "bounces_total": 0,
      "bounces_unique": 0,
      "bounces_unique_hard": 0,
      "bounces_unique_soft": 0,
      "bounces_unique_other": 0,
      "bounces_unique_local": 0,
      "bounces_unique_remote": 0,
      "clicks_total": 0,
      "clicks_unique": 0,
      "clicks_unique_by_link": 0,
      "opens_total": 0,
      "opens_unique": 0,
      "scomps_total": 0,
      "scomps_unique": 0,
      "scomps_status_updated": 0,
      "unsubs_total": 0,
      "unsubs_unique": 0,
      "unsubs_status_updated": 0,
      "bounces_status_updated": 0,
      "total_messages": 21,
      "total_success": 21,
      "total_failure": 0,
      "total_failure_toolong": 0,
      "skips_error": 0,
      "skips_request": 0,
      "stat_id": 5,
      "bounces_unique_by_code": {
      },
      "messages_sent": 21,
      "messages_html": 21,
      "messages_text": 0,
      "accepted": 21,
      "accepted_rate": 1.0,
      "in_queue": 0,
      "in_queue_rate": 0.0,
      "max_unique_activities": 0,
      "open_rate": 0.0,
      "open_ratio": 0.0,
      "unopened": 21,
      "duplicate_opens": 0,
      "duplicate_clicks": 0,
      "click_rate": 0.0,
      "click_to_open_rate": 0.0,
      "unclicked": 21,
      "bounced": 0,
      "duplicate_bounces": 0,
      "unbounced": 21,
      "bounce_rate": 0.0,
      "bounce_rate_hard": 0.0,
      "bounce_rate_soft": 0.0,
      "bounce_rate_other": 0.0,
      "bounce_local_rate": 0.0,
      "duplicate_scomps": 0,
      "scomp_rate": 0.0,
      "duplicate_unsubs": 0,
      "unsub_rate": 0.0
    },
    "content_stats": [
      {
        "content": {
          "id": 4,
          "name": "Content A"
        },
        "stat_summary": {
          "sent_text": 0,
          "sent_html": 19,
          "sent_multipart": 0,
          "bounces_total": 0,
          "bounces_unique": 0,
          "bounces_unique_hard": 0,
          "bounces_unique_soft": 0,
          "bounces_unique_other": 0,
          "bounces_unique_local": 0,
          "bounces_unique_remote": 0,
          "clicks_total": 0,
          "clicks_unique": 0,
          "clicks_unique_by_link": 0,
          "opens_total": 0,
          "opens_unique": 0,
          "scomps_total": 0,
          "scomps_unique": 0,
          "scomps_status_updated": 0,
          "unsubs_total": 0,
          "unsubs_unique": 0,
          "unsubs_status_updated": 0,
          "bounces_status_updated": 0,
          "total_messages": 19,
          "total_success": 19,
          "total_failure": 0,
          "total_failure_toolong": 0,
          "skips_error": 0,
          "skips_request": 0,
          "stat_slice_id": 6,
          "bounces_unique_by_code": {
          },
          "messages_sent": 19,
          "messages_html": 19,
          "messages_text": 0,
          "accepted": 19,
          "accepted_rate": 1.0,
          "in_queue": 0,
          "in_queue_rate": 0.0,
          "max_unique_activities": 0,
          "open_rate": 0.0,
          "open_ratio": 0.0,
          "unopened": 19,
          "duplicate_opens": 0,
          "duplicate_clicks": 0,
          "click_rate": 0.0,
          "click_to_open_rate": 0.0,
          "unclicked": 19,
          "bounced": 0,
          "duplicate_bounces": 0,
          "unbounced": 19,
          "bounce_rate": 0.0,
          "bounce_rate_hard": 0.0,
          "bounce_rate_soft": 0.0,
          "bounce_rate_other": 0.0,
          "bounce_local_rate": 0.0,
          "duplicate_scomps": 0,
          "scomp_rate": 0.0,
          "duplicate_unsubs": 0,
          "unsub_rate": 0.0
        }
      },
      {
        "content": {
          "id": 5,
          "name": "Content B"
        },
        "stat_summary": {
          "sent_text": 0,
          "sent_html": 0,
          "sent_multipart": 0,
          "bounces_total": 0,
          "bounces_unique": 0,
          "bounces_unique_hard": 0,
          "bounces_unique_soft": 0,
          "bounces_unique_other": 0,
          "bounces_unique_local": 0,
          "bounces_unique_remote": 0,
          "clicks_total": 0,
          "clicks_unique": 0,
          "clicks_unique_by_link": 0,
          "opens_total": 0,
          "opens_unique": 0,
          "scomps_total": 0,
          "scomps_unique": 0,
          "scomps_status_updated": 0,
          "unsubs_total": 0,
          "unsubs_unique": 0,
          "unsubs_status_updated": 0,
          "bounces_status_updated": 0,
          "total_messages": 0,
          "total_success": 0,
          "total_failure": 0,
          "total_failure_toolong": 0,
          "skips_error": 0,
          "skips_request": 0,
          "bounces_unique_by_code": null,
          "messages_sent": 0,
          "messages_html": 0,
          "messages_text": 0,
          "accepted": 0,
          "accepted_rate": 0.0,
          "in_queue": 0,
          "in_queue_rate": 0.0,
          "max_unique_activities": 0,
          "open_rate": 0.0,
          "open_ratio": 0.0,
          "unopened": 0,
          "duplicate_opens": 0,
          "duplicate_clicks": 0,
          "click_rate": 0.0,
          "click_to_open_rate": 0.0,
          "unclicked": 0,
          "bounced": 0,
          "duplicate_bounces": 0,
          "unbounced": 0,
          "bounce_rate": 0.0,
          "bounce_rate_hard": 0.0,
          "bounce_rate_soft": 0.0,
          "bounce_rate_other": 0.0,
          "bounce_local_rate": 0.0,
          "duplicate_scomps": 0,
          "scomp_rate": 0.0,
          "duplicate_unsubs": 0,
          "unsub_rate": 0.0
        }
      },
      {
        "content": {
          "id": 6,
          "name": "Content C"
        },
        "stat_summary": {
          "sent_text": 0,
          "sent_html": 2,
          "sent_multipart": 0,
          "bounces_total": 0,
          "bounces_unique": 0,
          "bounces_unique_hard": 0,
          "bounces_unique_soft": 0,
          "bounces_unique_other": 0,
          "bounces_unique_local": 0,
          "bounces_unique_remote": 0,
          "clicks_total": 0,
          "clicks_unique": 0,
          "clicks_unique_by_link": 0,
          "opens_total": 0,
          "opens_unique": 0,
          "scomps_total": 0,
          "scomps_unique": 0,
          "scomps_status_updated": 0,
          "unsubs_total": 0,
          "unsubs_unique": 0,
          "unsubs_status_updated": 0,
          "bounces_status_updated": 0,
          "total_messages": 2,
          "total_success": 2,
          "total_failure": 0,
          "total_failure_toolong": 0,
          "skips_error": 0,
          "skips_request": 0,
          "stat_slice_id": 8,
          "bounces_unique_by_code": {
          },
          "messages_sent": 2,
          "messages_html": 2,
          "messages_text": 0,
          "accepted": 2,
          "accepted_rate": 1.0,
          "in_queue": 0,
          "in_queue_rate": 0.0,
          "max_unique_activities": 0,
          "open_rate": 0.0,
          "open_ratio": 0.0,
          "unopened": 2,
          "duplicate_opens": 0,
          "duplicate_clicks": 0,
          "click_rate": 0.0,
          "click_to_open_rate": 0.0,
          "unclicked": 2,
          "bounced": 0,
          "duplicate_bounces": 0,
          "unbounced": 2,
          "bounce_rate": 0.0,
          "bounce_rate_hard": 0.0,
          "bounce_rate_soft": 0.0,
          "bounce_rate_other": 0.0,
          "bounce_local_rate": 0.0,
          "duplicate_scomps": 0,
          "scomp_rate": 0.0,
          "duplicate_unsubs": 0,
          "unsub_rate": 0.0
        }
      }
    ],
    "automatic_winner_selection": {
      "state": "finished",
      "winning_content": {
        "id": 4,
        "name": "Content A"
      },
      "snapshots": [
        {
          "content": {
            "id": 4,
            "name": "Content A",
            "is_winner": true
          },
          "snapshot": {
            "bounces_status_updated": 0,
            "bounces_total": 0,
            "bounces_unique": 0,
            "bounces_unique_by_code": {
            },
            "bounces_unique_hard": 0,
            "bounces_unique_local": 0,
            "bounces_unique_other": 0,
            "bounces_unique_remote": 0,
            "bounces_unique_soft": 0,
            "clicks_total": 0,
            "clicks_unique": 0,
            "clicks_unique_by_link": 0,
            "id": 1,
            "opens_total": 0,
            "opens_unique": 0,
            "scomps_status_updated": 0,
            "scomps_total": 0,
            "scomps_unique": 0,
            "sent_html": 2,
            "sent_multipart": 0,
            "sent_text": 0,
            "skips_error": 0,
            "skips_request": 0,
            "snapshot_group": "b7c306537082c5c5257d3203c12e97fd",
            "stat_id": 5,
            "stat_slice_id": 6,
            "taken_at": "2015-05-05T14:37:17Z",
            "total_failure": 0,
            "total_failure_toolong": 0,
            "total_messages": 2,
            "total_success": 2,
            "unsubs_status_updated": 0,
            "unsubs_total": 0,
            "unsubs_unique": 0
          }
        },
        {
          "content": {
            "id": 5,
            "name": "Content B",
            "is_winner": false
          },
          "snapshot": {
            "bounces_status_updated": 0,
            "bounces_total": 0,
            "bounces_unique": 0,
            "bounces_unique_by_code": {
            },
            "bounces_unique_hard": 0,
            "bounces_unique_local": 0,
            "bounces_unique_other": 0,
            "bounces_unique_remote": 0,
            "bounces_unique_soft": 0,
            "clicks_total": 0,
            "clicks_unique": 0,
            "clicks_unique_by_link": 0,
            "id": 2,
            "opens_total": 0,
            "opens_unique": 0,
            "scomps_status_updated": 0,
            "scomps_total": 0,
            "scomps_unique": 0,
            "sent_html": 0,
            "sent_multipart": 0,
            "sent_text": 0,
            "skips_error": 0,
            "skips_request": 0,
            "snapshot_group": "b7c306537082c5c5257d3203c12e97fd",
            "stat_id": 5,
            "stat_slice_id": 7,
            "taken_at": "2015-05-05T14:37:17Z",
            "total_failure": 0,
            "total_failure_toolong": 0,
            "total_messages": 0,
            "total_success": 0,
            "unsubs_status_updated": 0,
            "unsubs_total": 0,
            "unsubs_unique": 0
          }
        },
        {
          "content": {
            "id": 6,
            "name": "Content C",
            "is_winner": false
          },
          "snapshot": {
            "bounces_status_updated": 0,
            "bounces_total": 0,
            "bounces_unique": 0,
            "bounces_unique_by_code": {
            },
            "bounces_unique_hard": 0,
            "bounces_unique_local": 0,
            "bounces_unique_other": 0,
            "bounces_unique_remote": 0,
            "bounces_unique_soft": 0,
            "clicks_total": 0,
            "clicks_unique": 0,
            "clicks_unique_by_link": 0,
            "id": 3,
            "opens_total": 0,
            "opens_unique": 0,
            "scomps_status_updated": 0,
            "scomps_total": 0,
            "scomps_unique": 0,
            "sent_html": 2,
            "sent_multipart": 0,
            "sent_text": 0,
            "skips_error": 0,
            "skips_request": 0,
            "snapshot_group": "b7c306537082c5c5257d3203c12e97fd",
            "stat_id": 5,
            "stat_slice_id": 8,
            "taken_at": "2015-05-05T14:37:17Z",
            "total_failure": 0,
            "total_failure_toolong": 0,
            "total_messages": 2,
            "total_success": 2,
            "unsubs_status_updated": 0,
            "unsubs_total": 0,
            "unsubs_unique": 0
          }
        }
      ]
    },
    "dispatch": {
      "autowinner_delay_amount": 1,
      "autowinner_delay_unit": "minutes",
      "autowinner_enabled": true,
      "autowinner_metric": "opens_unique",
      "autowinner_percentage": "20.0",
      "begins_at": "2015-05-05T14:36:12Z",
      "finished_at": "2015-05-05T14:37:20Z",
      "from_email": "[email protected]",
      "from_name": "Studio Sender",
      "paused": false,
      "reply_to": "",
      "sender_email": "",
      "speed": 0,
      "started_at": "2015-05-05T14:36:15Z",
      "state": "finished",
      "track_links": true,
      "track_opens": true,
      "url_domain_id": 1,
      "virtual_mta_id": 0,
      "state_description": "Step 4: Finished",
      "virtual_mta_name": "System Default Route",
      "virtual_mta_type": "default_route",
      "bounce_email_user_id": 1,
      "bounce_email_domain_id": 1,
      "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": [
      {
        "id": 4,
        "name": "Content A",
        "subject": "aaaaa",
        "html": "<!DOCTYPE html>\n<html>\n<head>\n</head>\n<body>\n<p>aaaaa</p>\n</body>\n</html>",
        "text": "",
        "format": "html"
      },
      {
        "id": 5,
        "name": "Content B",
        "subject": "bbbb",
        "html": "<!DOCTYPE html>\n<html>\n<head>\n</head>\n<body>\n<p>bbbb</p>\n</body>\n</html>",
        "text": "",
        "format": "html"
      },
      {
        "id": 6,
        "name": "Content C",
        "subject": "cccc",
        "html": "<!DOCTYPE html>\n<html>\n<head>\n</head>\n<body>\n<p>cccc</p>\n</body>\n</html>",
        "text": "",
        "format": "html"
      }
    ],
    "segmentation_criteria_name": null
  },
  "error_code": null,
  "error_message": null
}

Create a New Campaign

URL

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

Request Parameters

The POST request should have a JSON document in its payload with at least keys listed as required in the following list:

source_template_id
integer

Use the specified template as a base when creating this new campaign. Any other fields supplied in this request will overwrite the values inherited from the template. See the fields duplicate_content, duplicate_segmentation_criteria, and duplicate_dispatch to specify what data to copy from the template.

duplicate_content
boolean

Copy the template’s content when creating the new campaign. Defaults to false.

duplicate_segmentation_criteria
boolean

Copy the template’s segment when creating the new campaign. Defaults to false.

The segmentation criteria will only be copied if the new campaign is on the same mailing list as the template specified in the source_template_id. If the source template and the new campaign are on different mailing lists then this attribute will have no effect.

duplicate_dispatch
boolean

Copy the template’s delivery settings when creating the new campaign. Defaults to false.

The delivery settings will only be copied if the new campaign is on the same mailing list as the template specified in the source_template_id. If the source template and the new campaign are on different mailing lists then this attribute will have no effect.

campaign
hash

name
string
/
required

The name of the campaign.

segmentation_criteria_id
integer

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

Only one of segmentation_criteria_id, segmentation_criteria_ad_hoc, and segmentation_criteria_remote_sql may be specified.

segmentation_criteria_ad_hoc
array of hashes

An ad hoc segment specification - see the Segment Definition page for more details. Only one of segmentation_criteria_id, segmentation_criteria_ad_hoc, and segmentation_criteria_remote_sql may be specified.

segmentation_criteria_remote_sql
integer

The SQL to use when querying the remote database for this campaign. This only applies to Remote Lists. Only one of segmentation_criteria_id, segmentation_criteria_ad_hoc, and segmentation_criteria_remote_sql may be specified.

contents
array of hashes

name string	String identifier for this content.
subject string	The subject of the email.
format string	Email format to use when delivering this campaign. 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
hash

state string	The state of delivery; Can be one of: `idle`, `scheduled`, `sending`, `finished`, `failed`, `cancelled`
state_description string	Localized textual description of the state.
virtual_mta_id integer	The id of a Virtual MTA explicitly assigned to the campaign; Will be blank if campaign is about to use general setting.
virtual_mta_name string	The name of a Virtual MTA explicitly assigned to the campaign.
bounce_email_id string	The id of a Bounce Email explicitly assigned to the campaign; Will come blank if campaign is about to use general setting.
bounce_email_name string	The Bounce Email explicitly assigned to the campaign.
url_domain_id integer	The id of an URL domain explicitly assigned to the campaign.
url_domain_name string	The URL domain explicitly assigned to the campaign.
seed_list_id integer	Deprecated: The id of the first seed list assigned to the campaign, ordered by id. Use `seed_lists` instead.
seed_list_name string	Deprecated: The name of the first seed list assigned to the campaign, ordered by id. Use `seed_lists` instead.
seed_list_ids array of integers	An array of seed lists assigned to the campaign, where each entry is the id of a seed list to use.
seed_list_names array of strings	An array of seed lists assigned to the campaign, where each entry is the name of a seed list to use.
speed integer	Maximum throughput speed; `0` for unlimited throughput.
track_opens boolean	Marks whether the campaign will track openings stats.
track_links boolean	Marks whether the campaign will track clicks stats.
paused boolean	Marks whether the campaign 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` field.
sender_email string	Email to use in the `Sender` field.
begins_at string	Time to start delivery at. If this value is specified and the campaign has a segment, content, and delivery settings - the campaign will be marked as scheduled and sending will begin at the requested time. If one of those sections are missing or this value is blank, the campaign will remain in an “idle” state.
autowinner_enabled boolean	The campaign is configured to use automatic winner selection.
autowinner_percentage string	The percentage that will be sent for the split-test portion of the campaign. See note (1) below.
autowinner_delay_amount integer	The number of units of time that the campaign will wait before finishing after a split-test.
autowinner_delay_unit integer	The unit used in calculating the delay duration. This may be `minutes`, `hours`, or `days`.
autowinner_metric string	The metric used to decide the winner. See the “Automatic Winner Selection Metrics” table for more information.
special_sending_rule_id integer	The id of the Special Sending Rule used for this campaign. Special Sending Rules may only be used on the System Organization. See note (4) below.
special_sending_rule_name string	The name of the Special Sending Rule used for this campaign. See note (4) below.

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 decimal places of precision.
Only one of seed_list_id, seed_list_name, seed_list_ids, and seed_list_names may be present in a single request.
Assigning to the deprecated fields seed_list_id or seed_list_name will assign the entire list of seed lists to the provided value, overwriting one or more seed lists that were already in use.
Only one of special_sending_rule_id and special_sending_rule_name may be present in a single request. Your organization must be granted access to Special Sending Rules by the system administrator.

Response

A successful response will return the campaign record using the format described in the “Get campaign details” section of the API.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

> POST /ga/api/mailing_lists/1/campaigns HTTP/1.1
> Authorization: Basic MTpkZDVjNmQ5NWM1Y2QyMDFmNDM1OTNhM2JlNjc4MmMyYjNhMGVhODhj
> Accept: application/json
> Content-Type: application/json

{
  "campaign": {
    "name": "Daily News 1002",
    "contents": [
      {
        "name": "multipart content",
        "format": "both",
        "subject": "this is my email",
        "html": "hello world",
        "text": "a text part"
      },
      {
        "name": "plaintext content",
        "format": "text",
        "subject": "this is my plaintext email",
        "text": "hello world"
      }
    ],
    "segmentation_criteria_ad_hoc": [

    ],
    "dispatch_attributes": {
      "state": "scheduled",
      "from_email": "[email protected]",
      "from_name": "From Example",
      "speed": 0,
      "virtual_mta_id": 0,
      "bounce_email_id": "1@1",
      "url_domain_id": 1,
      "begins_at": "2015-01-22 11:10AM CST",
      "track_opens": true,
      "track_links": "1"
    }
  }
}

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "1ff490406b54210615c6fdb88cc3d4c5"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=ec45b74de869d92a0a80b8108e2b2ac6; path=/; HttpOnly
< X-Request-Id: 6613fc943a2c20ff3571639c2c968c6e
< X-Runtime: 0.212025
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "data": {
    "archived": false,
    "content_determined": true,
    "created_at": "2015-05-05T20:34:41Z",
    "id": 5,
    "mailing_list_id": 1,
    "name": "Daily News 1002",
    "organization_id": 1,
    "segmentation_criteria_id": 5,
    "template": false,
    "updated_at": "2015-05-05T20:34:41Z",
    "mailing_list_name": "Default Mailing List",
    "organization_name": "System Organization",
    "stat_summary": null,
    "content_stats": [
      {
        "content": {
          "id": 11,
          "name": "multipart content"
        },
        "stat_summary": null
      },
      {
        "content": {
          "id": 12,
          "name": "plaintext content"
        },
        "stat_summary": null
      }
    ],
    "automatic_winner_selection": null,
    "dispatch": {
      "autowinner_delay_amount": null,
      "autowinner_delay_unit": "minutes",
      "autowinner_enabled": false,
      "autowinner_metric": null,
      "autowinner_percentage": null,
      "begins_at": "2015-01-22T17:10:00Z",
      "finished_at": null,
      "from_email": "[email protected]",
      "from_name": "From Example",
      "paused": false,
      "reply_to": null,
      "sender_email": null,
      "speed": 0,
      "started_at": null,
      "state": "scheduled",
      "track_links": true,
      "track_opens": true,
      "url_domain_id": 1,
      "virtual_mta_id": 0,
      "state_description": "Step 2: Scheduled",
      "virtual_mta_name": "System Default Route",
      "virtual_mta_type": "default_route",
      "bounce_email_user_id": 1,
      "bounce_email_domain_id": 1,
      "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": [
      {
        "id": 11,
        "name": "multipart content",
        "subject": "this is my email",
        "html": "hello world",
        "text": "a text part",
        "format": "both"
      },
      {
        "id": 12,
        "name": "plaintext content",
        "subject": "this is my plaintext email",
        "html": "",
        "text": "hello world",
        "format": "text"
      }
    ],
    "segmentation_criteria_name": null
  },
  "error_code": null,
  "error_message": null
}

Example Code

Update an Existing Campaign

URL

PUT /ga/api/v2/campaigns/:campaign_id

URL (Update Campaign Details by Stat ID Instead of Campaign ID)

PUT /ga/api/v2/campaigns/by_stat/:stat_id

Request Parameters

The PUT request should have a JSON document in its payload with the format described in the “Create a new campaign” section of the API.

Response

A successful response will return the campaign record using the format described in the “Get campaign details” section of the API.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

> PUT /ga/api/mailing_lists/1/campaigns/5 HTTP/1.1
> Authorization: Basic MTpkZDVjNmQ5NWM1Y2QyMDFmNDM1OTNhM2JlNjc4MmMyYjNhMGVhODhj
> Accept: application/json
> Content-Type: application/json

{
  "campaign": {
    "name": "My Campaign's New Name 3"
  }
}

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "37499a62c4458bd1fb26c47a1b010817"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=a8c605f6f4346e20a04f07058dc8e800; path=/; HttpOnly
< X-Request-Id: 1afa82fcf5f5c794c59d28d63ef3aa92
< X-Runtime: 0.037008
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "data": {
    "archived": false,
    "content_determined": true,
    "created_at": "2015-05-05T20:34:41Z",
    "id": 5,
    "mailing_list_id": 1,
    "name": "My Campaign's New Name 3",
    "organization_id": 1,
    "segmentation_criteria_id": 5,
    "template": false,
    "updated_at": "2015-05-05T20:38:52Z",
    "mailing_list_name": "Default Mailing List",
    "organization_name": "System Organization",
    "stat_summary": {
      "sent_text": 11,
      "sent_html": 0,
      "sent_multipart": 10,
      "bounces_total": 0,
      "bounces_unique": 0,
      "bounces_unique_hard": 0,
      "bounces_unique_soft": 0,
      "bounces_unique_other": 0,
      "bounces_unique_local": 0,
      "bounces_unique_remote": 0,
      "clicks_total": 0,
      "clicks_unique": 0,
      "clicks_unique_by_link": 0,
      "opens_total": 0,
      "opens_unique": 0,
      "scomps_total": 0,
      "scomps_unique": 0,
      "scomps_status_updated": 0,
      "unsubs_total": 0,
      "unsubs_unique": 0,
      "unsubs_status_updated": 0,
      "bounces_status_updated": 0,
      "total_messages": 21,
      "total_success": 21,
      "total_failure": 0,
      "total_failure_toolong": 0,
      "skips_error": 0,
      "skips_request": 0,
      "stat_id": 15,
      "bounces_unique_by_code": {
      },
      "messages_sent": 21,
      "messages_html": 10,
      "messages_text": 11,
      "accepted": 21,
      "accepted_rate": 1.0,
      "in_queue": 0,
      "in_queue_rate": 0.0,
      "max_unique_activities": 0,
      "open_rate": 0.0,
      "open_ratio": 0.0,
      "unopened": 21,
      "duplicate_opens": 0,
      "duplicate_clicks": 0,
      "click_rate": 0.0,
      "click_to_open_rate": 0.0,
      "unclicked": 21,
      "bounced": 0,
      "duplicate_bounces": 0,
      "unbounced": 21,
      "bounce_rate": 0.0,
      "bounce_rate_hard": 0.0,
      "bounce_rate_soft": 0.0,
      "bounce_rate_other": 0.0,
      "bounce_local_rate": 0.0,
      "duplicate_scomps": 0,
      "scomp_rate": 0.0,
      "duplicate_unsubs": 0,
      "unsub_rate": 0.0
    },
    "content_stats": [
      {
        "content": {
          "id": 11,
          "name": "multipart content"
        },
        "stat_summary": {
          "sent_text": 0,
          "sent_html": 0,
          "sent_multipart": 10,
          "bounces_total": 0,
          "bounces_unique": 0,
          "bounces_unique_hard": 0,
          "bounces_unique_soft": 0,
          "bounces_unique_other": 0,
          "bounces_unique_local": 0,
          "bounces_unique_remote": 0,
          "clicks_total": 0,
          "clicks_unique": 0,
          "clicks_unique_by_link": 0,
          "opens_total": 0,
          "opens_unique": 0,
          "scomps_total": 0,
          "scomps_unique": 0,
          "scomps_status_updated": 0,
          "unsubs_total": 0,
          "unsubs_unique": 0,
          "unsubs_status_updated": 0,
          "bounces_status_updated": 0,
          "total_messages": 10,
          "total_success": 10,
          "total_failure": 0,
          "total_failure_toolong": 0,
          "skips_error": 0,
          "skips_request": 0,
          "stat_slice_id": 16,
          "bounces_unique_by_code": {
          },
          "messages_sent": 10,
          "messages_html": 10,
          "messages_text": 0,
          "accepted": 10,
          "accepted_rate": 1.0,
          "in_queue": 0,
          "in_queue_rate": 0.0,
          "max_unique_activities": 0,
          "open_rate": 0.0,
          "open_ratio": 0.0,
          "unopened": 10,
          "duplicate_opens": 0,
          "duplicate_clicks": 0,
          "click_rate": 0.0,
          "click_to_open_rate": 0.0,
          "unclicked": 10,
          "bounced": 0,
          "duplicate_bounces": 0,
          "unbounced": 10,
          "bounce_rate": 0.0,
          "bounce_rate_hard": 0.0,
          "bounce_rate_soft": 0.0,
          "bounce_rate_other": 0.0,
          "bounce_local_rate": 0.0,
          "duplicate_scomps": 0,
          "scomp_rate": 0.0,
          "duplicate_unsubs": 0,
          "unsub_rate": 0.0
        }
      },
      {
        "content": {
          "id": 12,
          "name": "plaintext content"
        },
        "stat_summary": {
          "sent_text": 11,
          "sent_html": 0,
          "sent_multipart": 0,
          "bounces_total": 0,
          "bounces_unique": 0,
          "bounces_unique_hard": 0,
          "bounces_unique_soft": 0,
          "bounces_unique_other": 0,
          "bounces_unique_local": 0,
          "bounces_unique_remote": 0,
          "clicks_total": 0,
          "clicks_unique": 0,
          "clicks_unique_by_link": 0,
          "opens_total": 0,
          "opens_unique": 0,
          "scomps_total": 0,
          "scomps_unique": 0,
          "scomps_status_updated": 0,
          "unsubs_total": 0,
          "unsubs_unique": 0,
          "unsubs_status_updated": 0,
          "bounces_status_updated": 0,
          "total_messages": 11,
          "total_success": 11,
          "total_failure": 0,
          "total_failure_toolong": 0,
          "skips_error": 0,
          "skips_request": 0,
          "stat_slice_id": 17,
          "bounces_unique_by_code": {
          },
          "messages_sent": 11,
          "messages_html": 0,
          "messages_text": 11,
          "accepted": 11,
          "accepted_rate": 1.0,
          "in_queue": 0,
          "in_queue_rate": 0.0,
          "max_unique_activities": 0,
          "open_rate": 0.0,
          "open_ratio": 0.0,
          "unopened": 11,
          "duplicate_opens": 0,
          "duplicate_clicks": 0,
          "click_rate": 0.0,
          "click_to_open_rate": 0.0,
          "unclicked": 11,
          "bounced": 0,
          "duplicate_bounces": 0,
          "unbounced": 11,
          "bounce_rate": 0.0,
          "bounce_rate_hard": 0.0,
          "bounce_rate_soft": 0.0,
          "bounce_rate_other": 0.0,
          "bounce_local_rate": 0.0,
          "duplicate_scomps": 0,
          "scomp_rate": 0.0,
          "duplicate_unsubs": 0,
          "unsub_rate": 0.0
        }
      }
    ],
    "automatic_winner_selection": null,
    "dispatch": {
      "autowinner_delay_amount": null,
      "autowinner_delay_unit": "minutes",
      "autowinner_enabled": false,
      "autowinner_metric": null,
      "autowinner_percentage": null,
      "begins_at": "2015-01-22T17:10:00Z",
      "finished_at": "2015-05-05T20:34:48Z",
      "from_email": "[email protected]",
      "from_name": "From Example",
      "paused": false,
      "reply_to": null,
      "sender_email": null,
      "speed": 0,
      "started_at": "2015-05-05T20:34:44Z",
      "state": "finished",
      "track_links": true,
      "track_opens": true,
      "url_domain_id": 1,
      "virtual_mta_id": 0,
      "state_description": "Step 4: Finished",
      "virtual_mta_name": "System Default Route",
      "virtual_mta_type": "default_route",
      "bounce_email_user_id": 1,
      "bounce_email_domain_id": 1,
      "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": [
      {
        "id": 11,
        "name": "multipart content",
        "subject": "this is my email",
        "html": "hello world",
        "text": "a text part",
        "format": "both"
      },
      {
        "id": 12,
        "name": "plaintext content",
        "subject": "this is my plaintext email",
        "html": "",
        "text": "hello world",
        "format": "text"
      }
    ],
    "segmentation_criteria_name": null
  },
  "error_code": null,
  "error_message": null
}

Pause a Campaign

URL

POST /ga/api/v2/campaigns/:campaign_id/pause

URL (Pause a Campaign by Stat ID Instead of Campaign ID)

POST /ga/api/v2/campaigns/by_stat/:stat_id/pause

Request Parameters

This API method does not require any additional parameters.

Response

A successful response will return the campaign record using the format described in the “Get campaign details” section of the API.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

Resume a Campaign

URL

POST /ga/api/v2/campaigns/:campaign_id/resume

URL (Resume a Campaign by Stat ID Instead of Campaign ID)

POST /ga/api/v2/campaigns/by_stat/:stat_id/resume

Request Parameters

This API method does not require any additional parameters.

Response

A successful response will return the campaign record using the format described in the “Get campaign details” section of the API.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

> POST /ga/api/v2/mailing_lists/1/campaigns/1/resume HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1Yzg4M2YzMzA5ZjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: greenarrow-studio.dev
> Accept: */*
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< Set-Cookie: _session_id=458055a23f26f844e74f8cd7300f6445; path=/; HttpOnly
< X-Request-Id: f6e40d578ed1d9c418cca45e1b7fe532
< X-Runtime: 0.025540
< Connection: close

{
  "error_message" : null,
  "data" : {
    "mailing_list_name" : "adsfadf",
    "content_subject" : "asdfadf",
    "content_text" : "",
    "updated_at" : "2013-09-02T16:26:45Z",
    "segmentation_criteria_id" : 1,
    "archived" : false,
    "name" : "asdf",
    "content_html" : "<html>\n<head>\n\t<title></title>\n</head>\n<body>\n<p>adfadf</p>\n</body>\n</html>\n",
    "content_determined" : true,
    "id" : 4,
    "organization_id" : 1,
    "organization_name" : "System Organization",
    "dispatch" : {
      "reply_to" : "",
      "seed_list_id" : null,
      "seed_list_name" : null,
      "seed_lists" : [],
      "paused" : false,
      "virtual_mta_id" : 0,
      "from_email" : "[email protected]",
      "speed" : 0,
      "state_description" : "Step 1: Pending",
      "track_opens" : true,
      "sender_email" : "",
      "state" : "idle",
      "from_name" : "Fo",
      "url_domain_id" : 1,
      "virtual_mta_type" : "default_route",
      "virtual_mta_name" : "System Default Route",
      "finished_at" : null,
      "bounce_email_user_id" : 1,
      "bounce_email_domain_id" : 1,
      "bounce_email_email" : "test@test",
      "started_at" : null,
      "url_domain_domain" : "test",
      "begins_at" : null,
      "autowinner_enabled": true,
      "autowinner_percentage": "25.0",
      "autowinner_delay_amount": 10,
      "autowinner_delay_unit": "hours",
      "autowinner_metric": "opens_unique",
      "special_sending_rule_id": null,
      "special_sending_rule_name": null
    },
    "stats" : null,
    "mailing_list_id" : 1,
    "email_format" : "html",
    "created_at" : "2013-09-02T16:25:57Z"
  },
  "error_code" : null,
  "success" : true
}

Get Campaign Per-Link Statistics

Get statistics for this campaign, broken down per-link.

Campaigns generate link entries during delivery. Thus if a campaign hasn’t yet delivered, this API will return an empty list.

URL

GET /ga/api/v2/campaigns/:campaign_id/link_stats

Request Parameters

Optional Parameters

url string	If specified, only return links to the specified URL. The specified URL may contain wildcards (`*`) to match multiple URLs.
content_id string	If specified, only return statistics for the specified content id. The content id may be obtained from the `Get campaign details` endpoint.

The value of the url parameter must be URI encoded.

Pagination

The links returned by this API are sorted first by their case-insensitive url, then by link_id.

To query additional records, provide page and per_page parameters. The page parameter starts at 0. The per_page parameter defaults to 100 and the maximum allowed is 500.

For example to get the second page:

GET /ga/api/v2/campaigns/:campaign_id/link_stats?scope=all&page=1&per_page=100

The response will also contain the following extra parameters:

page	The current page number
per_page	The number of records per page
num_records	The total number of records that match the query
num_pages	The total number of pages that match the query

Response

all_unclicked_links_recorded
boolean

If this value is false, the list of links available via this API is not a comprehensive list of links that were delivered in this campaign. Some links that have not received clicks may not be present. Links that have received at least one click will always be available in this API, regardless of the value of all_unclicked_links_recorded.

(This happens when an email campaign has more links than should be recorded in the database. This generally happens when a Special Sending Rule create custom links for each subscriber.)

If this value is true, all links delivered in this campaign are available via this API.

links
array of hashes

link_id integer	Internal identifier for this link
url string	The URL of the link
clicks_total integer	Total number of clicks on this link
clicks_unique integer	Number of “unique clicks by subscriber” that happened on this link
clicks_unique_by_link integer	Number of “unique clicks by subscriber/link” that happened on this link

Example

Note that the JSON response will not be “pretty formatted” as it is below.

> GET /ga/api/campaigns/2/link_stats HTTP/1.1
> Authorization: Basic MTowYWUyNTJlMjA3MjkyNDcwYzViMTc0ZTk0MzhlNmU3MzMzZjJkNmU3
> Accept: application/json
> Content-Type: application/json

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "1f1fcc31723ce7df22f373ea3c568816"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=c0dcd71b03ad686d3102e24b3debf7ff; path=/; HttpOnly
< X-Request-Id: 4f5199066ea241610046a19b00bad99c
< X-Runtime: 0.026501
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "data": {
    "all_unclicked_links_recorded": true,
    "links": [
      {
        "clicks_total": 6,
        "clicks_unique": 0,
        "clicks_unique_by_link": 1,
        "link_id": 3,
        "url": "https://www.greenarrowemail.com"
      },
      {
        "clicks_total": 1,
        "clicks_unique": 1,
        "clicks_unique_by_link": 1,
        "link_id": 4,
        "url": "http://duckduckgo.com"
      },
      {
        "clicks_total": 1,
        "clicks_unique": 0,
        "clicks_unique_by_link": 1,
        "link_id": 5,
        "url": "https://www.eff.org"
      }
    ]
  },
  "num_records": 3,
  "num_pages": 1
}

Estimate Number of Recipients in Campaign

This API is used to estimate the number of recipients that would be included in a campaign were it to be sent.

This API can be used on any campaign that has its segment and delivery settings defined.

This API endpoint is ordinarily called multiple times. The first time you call it, a background job will be enqueued to execute the count of the number of recipients. Subsequent times you call it, you’ll either be told that the estimate is not yet ready (signaled by the estimate_is_ready attribute), or the estimate will be provided.

We recommend that you add an artificial delay between calls to this endpoint (something on the order of 100ms is safe and effective).

Once generated, the estimate will be cached and return the same values for the next 8 hours. If you want to clear this cache early to get a fresh estimate, provide the ?clear_cache attribute in a single API call (then resume querying it without the ?clear_cache attribute until the estimate is ready). Modifying the segment definition will also cause this cache to be invalidated.

URL

GET /ga/api/v2/campaigns/:campaign_id/estimate_recipients
GET /ga/api/v2/campaigns/:campaign_id/estimate_recipients?clear_cache

Response

{apitable}

estimate_is_ready (boolean):

    This value will be true if the `estimate` field is populated.

estimate (hash):

    number_of_recipients (integer):

        The estimated number of recipients that would actually receive this
        campaign if it were sent now.

    number_of_recipients_suppressed (integer):

        The estimated number of recipients that would have been included in
        this campaign, but were suppressed by one or more suppression
        lists.

    time_generated (time):

        The time at which this estimate was generated.