System Campaigns API

Get a list of campaigns across all organizations

This API provides a way for system administrators to access the list of all
campaigns that have started sending, across the system.

  • Campaigns that are currently sending
  • Campaigns that started sending and were subsequently paused
  • Campaigns that failed or were cancelled
  • Campaigns that finished sending

The API user that accesses this endpoint must be a system_admin.

URL

GET /ga/api/v2/system_campaigns

Request Parameters

This endpoint accepts pagination parameters.

Key Description
page The page number to return (starting at 0)
per_page The number of records per page (default 100, maximum 500)

This endpoint also accepts parameters to filter based on the time that the campaign started.

Key Description
started_at__start An ISO 8601 Date/Time string representing the earliest started_at time to include.
started_at__end An ISO 8601 Date/Time string representing the latest started_at time to include.

Furthermore, you can provide provide a key to exclude sending campaigns from this report.

Key Description
exclude_active_campaigns Only report campaigns that are Finished, Cancelled or Failed (value: 1 or 0).

Pagination Order

The campaigns returned are sorted in the following order:

  1. By the time the campaign started sending (this is usually unique)
  2. By the campaign ID

Response

campaign_reportarray of hashes

organizationhash

id
integer
Organization ID
name
string
Organization Name
mailing_listhash

id
integer
Mailing List ID
name
string
Mailing List Name
campaignhash

id
integer
Campaign ID
name
string
Campaign Name
state
string
Campaign State (sending, finished, failed, cancelled)
paused
boolean
The campaign is currently paused.
stats
hash

recipientshash

total
integer
Total recipients in this campaign
sent
integer
Number of recipients that were sent an email
skip
integer
Number of recipients that were skipped due to Special Sending Rules
remaining
integer
Number of recipients remaining in this campaign
senthash

total
integer
Total messages sent so far in this campaign
accepted
integer
Number of messages that have been accepted by a SMTP server (and are no longer in Engine’s queue)
bounced
integer
Number of messages that resulted in bounces
in_queue
integer
Number of messages in Engine’s queue waiting for delivery
skiphash

ssr_failure
integer
Number of messages that failed because of an error in a Special Sending Rule
ssr_request
integer
Number of messages that were skipped because a Special Sending Rule indicated it should be skipped
openhash

total
integer
Total number of opens / renders, including duplicates
unique
integer
Number of unique opens / renders
clickhash

total
integer
Total number of clicks, including duplicates
unique
integer
Number of unique clicks
bouncehash

total
integer
Total number of bounces, including duplicates
unique
integer
Number of unique bounces
hard
integer
Number of unique hard bounces
soft
integer
Number of unique soft bounces
other
integer
Number of unique other bounces
subscribers_updated
integer
Number of subscribers whose status changed due to a bounce
scomphash

total
integer
Total number of spam complaints, including duplicates
unique
integer
Number of unique spam complaints
subscribers_updated
integer
Number of subscribers whose status changed due to a spam complaint
unsubhash

total
integer
Total number of unsubscribes, including duplicates
unique
integer
Number of unique unsubscribes
subscribers_updated
integer
Number of subscribers whose status changed due to an unsubscribe

This endpoint also returns pagination details.

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

Example

> GET /ga/api/system_campaigns HTTP/1.1
> Authorization: Basic MTozNTZjNTg0ZWM4YWJlMWQ0NDY0OGZlMTY3MmVkM2ZlYmVkYTQxNWRh
> Accept: application/json
> Content-Type: application/json

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "427f115a558eb8134d5d20711c6e276e"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=dad8e99250c3941d201628a809cf4f85; path=/; HttpOnly
< X-Request-Id: 827177bb507f40519e575d74b25898e4
< X-Runtime: 0.058486
< Connection: close
< Server: thin 1.5.0 codename Knife
{
  "success": true,
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "data": {
    "campaign_report": [
      {
        "organization": {
          "id": 1,
          "name": "System Organization"
        },
        "mailing_list": {
          "id": 1,
          "name": "Default Mailing List"
        },
        "campaign": {
          "id": 1,
          "name": "Default Campaign",
          "state": "failed",
          "stats": {
            "recipients": {
              "total": 2,
              "sent": 1,
              "skip": 1,
              "remaining": 1
            },
            "sent": {
              "total": 0,
              "accepted": 0,
              "bounced": 0,
              "in_queue": 0
            },
            "skip": {
              "ssr_failure": 0,
              "ssr_request": 1
            },
            "open": {
              "total": 0,
              "unique": 0
            },
            "click": {
              "total": 0,
              "unique": 0
            },
            "bounce": {
              "total": 0,
              "unique": 0,
              "hard": 0,
              "soft": 0,
              "other": 0,
              "subscribers_updated": 0
            },
            "scomp": {
              "total": 0,
              "unique": 0,
              "subscribers_updated": 0
            },
            "unsub": {
              "total": 0,
              "unique": 0,
              "subscribers_updated": 0
            }
          }
        }
      },
      {
        "organization": {
          "id": 1,
          "name": "System Organization"
        },
        "mailing_list": {
          "id": 1,
          "name": "Default Mailing List"
        },
        "campaign": {
          "id": 2,
          "name": "Default Campaign (Duplicate #1)",
          "state": "failed",
          "stats": {
            "recipients": {
              "total": 2,
              "sent": 1,
              "skip": 1,
              "remaining": 1
            },
            "sent": {
              "total": 0,
              "accepted": 0,
              "bounced": 0,
              "in_queue": 0
            },
            "skip": {
              "ssr_failure": 0,
              "ssr_request": 1
            },
            "open": {
              "total": 0,
              "unique": 0
            },
            "click": {
              "total": 0,
              "unique": 0
            },
            "bounce": {
              "total": 0,
              "unique": 0,
              "hard": 0,
              "soft": 0,
              "other": 0,
              "subscribers_updated": 0
            },
            "scomp": {
              "total": 0,
              "unique": 0,
              "subscribers_updated": 0
            },
            "unsub": {
              "total": 0,
              "unique": 0,
              "subscribers_updated": 0
            }
          }
        }
      }
    ]
  }
}