Campaigns API

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.

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.

name

string

The name of the Campaign
mailing_list_id

integer

The id of a Mailing List the Campaign belongs to
mailing_list_name

string

The name of a Mailing List the Campaign belongs to
dispatch

hash


Inline object containing delivery settings of the Campaign; Comes from the server only if delivery settings of the Campaign are defined

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"
paused

boolean

Marks whether the Campaign has been paused
begins_at

DateTime

Time to start delivery at
started_at

DateTime

Time when delivery actually started
finished_at

DateTime

Time when delivery has finished

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: SendSage-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",
      "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 SendSage 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 SendSage 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.

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 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.
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 SendSage 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 SendSage Engine’s delivery queue.
in_queue_rate

float

Ratio of the total number of messages that have been handed off to SendSage 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.
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 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.drh.net",
      "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 segmentation criteria 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 segmentation criteria specification – see the “Ad Hoc Segmentation Criteria” section below 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 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

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.

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: SendSage-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,
    "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

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 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://drh.net"
      },
      {
        "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
}
 "Campaign Templates API"
"Custom Fields API"