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

Key Description
started_at__start A UNIX integer timestamp or ISO-8601 datetime string representing the earliest started_at time to include.
started_at__end A UNIX integer timestamp or ISO-8601 datetime string representing the latest started_at time to include.

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 will be a JSON array where each element contains the following keys.

Key Meaning Example Type
name The name of the Campaign Campaign 1 String
mailing_list_id The id of a Mailing List the Campaign belongs to 1 Integer
mailing_list_name The name of a Mailing List the Campaign belongs to Mailing List 1 String
dispatch Inline object containing delivery settings of the Campaign; Comes from the server only if delivery settings of the Campaign are defined {} Hash
dispatch.state The state of delivery; Can be one of: idle, scheduled, sending, finished, failed, cancelled failed String
dispatch.state_description Localized textual description of the state Step 2: Scheduled String
dispatch.paused Marks whether the Campaign has been paused false Boolean
dispatch.begins_at Time to start delivery at 2013-01-01T00:00:00Z DateTime
dispatch.started_at Time when delivery actually started 2013-01-01T00:00:00Z DateTime
dispatch.finished_at Time when delivery has finished 2013-01-01T00:00:00Z DateTime

Example Request

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: InboxFirst.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",
      "active_html_editor" : "wysiwyg",
      "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 InboxFirst Engine's API.

Response

[nomarkdown]

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 InboxFirst 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 segmentation criteria to use when delivering this campaign.
segmentation_criteria_name
string		 The name of the segmentation criteria, if it is a stored segment.
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 the "Automatic Winner Selection Metrics" table for more information.
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.
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 InboxFirst 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 InboxFirst Engine's delivery queue.
in_queue_rate
float		 Ratio of the total number of messages that have been handed off to InboxFirst 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.
content_stats
array of hashes
content
hash
id
integer		 The ID of this content.
sent_html
integer		 The name of this content.
content
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.

Example Request

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": {
    "active_html_editor": "wysiwyg",
    "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,
      "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,
          "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,
          "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,
          "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": "sender@discardallmail.inboxfirst.com",
      "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": "return@example.com",
      "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 that marked with bold 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.
duplicate_dispatch
boolean		 Copy the template's delivery settings when creating the new campaign. Defaults to false.
campaign
hash
name
string		 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 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 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 come 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
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 the "Automatic Winner Selection Metrics" table for more information.
  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.

Ad Hoc Segmentation Criteria

An ad hoc segmentation criteria may be specified to generate a basic segmentation criteria for a campaign.

The ad hoc segmentation criteria is an array of clauses, all of which must be true for each subscriber record to be included in the campaign.

Specifying an empty array [] is equivalent to sending to "All Active Subscribers".

In Mailing List

An ad hoc segment may include a clause restricting the included subscribers to those whose email address exists on another mailing list.

Example:

{
  "segmentation_criteria_ad_hoc": [
    { "type": "in_mailing_list", "operator": "is_in", "mailing_list_id": 12 }
  ]
}

This campaign would be sent to "All Active Subscribers whose email address exists on mailing list #12".

Example with multiple clauses:

{
  "segmentation_criteria_ad_hoc": [
    { "type": "in_mailing_list", "operator": "is_in", "mailing_list_id": 12 },
    { "type": "in_mailing_list", "operator": "is_not_in", "mailing_list_id": 14 }
  ]
}

This campaign would be sent to "All Active Subscribers whose email address exists on mailing list #12 AND NOT in mailing list #14".

Response

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

Example Request

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": "from@example.com",
      "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": {
    "active_html_editor": "wysiwyg",
    "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": "from@example.com",
      "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": "return@example.com",
      "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 Request

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": {
    "active_html_editor": "wysiwyg",
    "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,
      "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,
          "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,
          "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": "from@example.com",
      "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": "return@example.com",
      "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 campaign 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 Request

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 Request

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: InboxFirst.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,
    "active_html_editor" : "wysiwyg",
    "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" : "foo@example.com",
      "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

Key Meaning
url If specified, only return links to the specified URL. The specified URL may contain wildcards (*) to match multiple URLs.
content_id 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:

Key Description
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

{::nomarkdown}

all_unclicked_links_recorded
bool

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
{:/nomarkdown}

Example Request

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": "http://inboxfirst.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
}