How to retrieve data from the Campaign Statistics API?

The campaign data can be used to feed external tools such as PowerBI or Segmental by our partner 70/30 Digital for in-depth analysis. The API is currently in active development and subject to change.

Please note! The Campaign Statistics API beta version endpoint continues to exist, but we recommend updating to the new endpoint.

Base URL

GET /api/campaign/actions/

Authentication

This API uses token-based authentication. For instructions on how to obtain a token, see the API Authentication documentation.

- headers:
- Authorization: Bearer <token>

Query Parameters

Each campaign gets sales (conversion) statistics starting from their
activation date to 30 days after, same as in the UI.
keys: The response will be filtered to give only the requested campaigns if the keys parameter is used.
Format: string (example: "CA-1,CA-3") (for paging)
limit: how many campaigns in a response.
- Format: integer.
- Default: 30.
order: ordering by date.
- Format: must be "descending" or "ascending".
- Default: descending
from: paging control, you may use the value of the parameter `next` returned in any previous request to this endpoint. (e.g.: i1967)

Response Format

The response contains paging information and a list of campaign objects.

Response Example

{
    /*
        ...paging info
    */
    "campaigns": [
        ..., // campaign objects
        {
            "campaign_key": "EMAIL-A-123",
            "kind": "automated-email",
            "automated": true, // added for easier access to this info, "kind" should be distinct still though
            "name": "Welcome email",
            "state": "active",
            "utm_campaign": "some-tag" // only for "email" campaigns with custom tags, default tag not included
            "campaign_tags": ["tag", ...] // or []
            "folder": {
                "id": 123,
                "name": "Welcome emails"
            },
            "permissions": { // MR 3985
                "marketing_permission": "can_email", // or can_sms, etc
            },
            "stats": { // None for draft campaigns and EXT campaigns
                "date_range": { // Only for automated campaigns
                    "start": "2024-06-01T00:00:00Z", // activation
                    "end": "2024-06-31T23:59:59Z" // 30 days after activation
                },
                "audience_size": 123,
                "audience_with_events": 123,
                "audience_with_sales": 123,
                "sales_for_conversion": 123,
                "audience_unreachable": 123,
                "audience_no_reaction": 123,
                "events": [
                    { "name": "sent", "count": 123 },
                    { "name": "delivered", "count": 123 },
                    { "name": "opens", "count": 123 },
                    { "name": "clicks", "count": 123 },
                    { "name": "unsubscribes", "count": 123 },
                    { "name": "spam_reports", "count": 123 },
                    { "name": "bounces", "count": 123 },
                ],
                "sales": {
                    "date_range": {
                        "start": "2024-06-01", // activation
                        "end": "2024-06-31" // 30 days after activation
                    },
                    "total_sales": 123,
                    "total_revenue": 123,
                    "average_products_count": 123,
                    "total_products_count": 123,
                    "campaign_product_count": 123,
                    "campaign_product_revenue": 123,
                    "other_product_count": 123,
                    "other_product_revenue": 123,
                    "product_categories": [
                        {
                            "discount": 0,
                            "revenue": 599.0,
                            "title": "C",
                            "units": 5.0
                        },
                        ...
                    ],
                },
                "cache_modified_at": "2024-06-31T12:00:00Z", // or None if not cached
            }
        },
        ...
    ],
    "next": "i1976" // next identifier, used to find the start of the next "page"
}

Paging

By default, the API returns a maximum of 30 campaigns per request, sorted by the most recent first. Use the limit, order, and from query parameters to control paging.

Notes

Campaigns of type EXT and campaigns in draft state will not include statistics.
Campaign statistics for the last 7 days are cached every hour, and for campaigns older than 7 days (but within 30 days), the cache is updated every 24 hours.
The more campaigns you retrieve the slower it can be. So changing the limit from 30 (default) to 100 may have a significant impact making multiple fetches might be more reliable so systems do not timeout.