System Campaigns API

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.

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.

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.

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_report

array of hashes



Array where each item is an organization with the following attributes.

id

integer

Organization ID

name

string

Organization Name

mailing_list

hash


id

integer

Mailing List ID

name

string

Mailing List Name

campaign

hash


id

integer

Campaign ID

name

string

Campaign Name

state

string

Campaign State (sending, finished, failed, cancelled)

paused

string

Whether the campaign is currently paused.

stats

hash


recipients

hash


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

sent

hash


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

skip

hash


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

open

hash


total

integer

Total number of opens / renders, including duplicates

unique

integer

Number of unique opens / renders

click

hash


total

integer

Total number of clicks, including duplicates

unique

integer

Number of unique clicks

bounce

hash


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

scomp

hash


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

unsub

hash


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.

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
            }
          }
        }
      }
    ]
  }
}