GreenArrow Email Software Documentation

Campaigns API

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.

  1. 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.

  1. 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.
  2. Only one of seed_list_id, seed_list_name, seed_list_ids, and seed_list_names may be present in a single request.
  3. 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.
  4. 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 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.

Copyright © 2012–2024 GreenArrow Email