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: SMTPProvider-Application.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" : "ckeditor",
      "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
SMTPProvider 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 SMTPProvider 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.
segmentation_criteria_remote_sql
string
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 Application 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 SMTPProvider Application 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 SMTPProvider Engine’s delivery queue.
in_queue_rate
float
Ratio of the total number of messages that have been handed off to SMTPProvider 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.

  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": "ckeditor",
    "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": "Application 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
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.
  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": "ckeditor",
    "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": "ckeditor",
    "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: SMTPProvider-Application.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" : "ckeditor",
    "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

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

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
}