Request totals

Overview

Get totals across all campaigns: emails sent, delivered, opened, clicked and unsubscribed; texts sent, delivered, clicked and failed; and the new contacts added, against the previous period.

Use this for a campaigns dashboard header.

You'll need an account token and a period. Test sends aren't counted.

Returns the totals.

Prerequisites

A bearer token. See Authentication.
A period (start_date, end_date), both Y-m-d.
Optional: a location (store_id).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/campaign/dashboard/metrics

Authentication

Account token

The totals cover the campaigns of the caller's own company.
store_id must be inside your own account tree; otherwise 422.

Rate limit

120 requests per minute, counted per user (the token’s user). See Rate limits.

Request parameters

Parameter	In	Type	Required	Description
`start_date`	query	string	Yes	Start of the period, `Y-m-d`.
`end_date`	query	string	Yes	End of the period, `Y-m-d`. Must be on or after `start_date`.
`store_id`	query	integer	No	Only the campaigns of this location. Must be inside your account tree.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`data`	object	The totals.
`data.email_performance`	object	Email requests in the period (test sends left out).
`data.email_performance.sent`	integer	Emails sent in the period.
`data.email_performance.delivered`	integer	Emails delivered in the period.
`data.email_performance.opened`	integer	Emails opened in the period.
`data.email_performance.clicked`	integer	Emails with a link clicked in the period.
`data.email_performance.unsubscribed`	integer	Unsubscribes in the period.
`data.email_performance.rates`	object	Percentages, 2 decimals; `0` when the base is 0.
`data.email_performance.rates.delivered`	number	`delivered` as a percentage of `sent`.
`data.email_performance.rates.opened`	number	`opened` as a percentage of `sent`.
`data.email_performance.rates.clicked`	number	`clicked` as a percentage of `sent`.
`data.email_performance.rates.unsubscribed`	number	`unsubscribed` as a percentage of `sent`.
`data.email_performance.rates.sent`	number	`sent` as a percentage of the contacts with a valid email added in the period.
`data.sms_performance`	object	Text (SMS) requests in the period (test sends left out).
`data.sms_performance.sent`	integer	Texts sent in the period.
`data.sms_performance.delivered`	integer	Texts delivered in the period.
`data.sms_performance.link_clicked`	integer	Texts with the link clicked in the period.
`data.sms_performance.failed`	integer	Texts that failed in the period.
`data.sms_performance.rates`	object	Percentages, 2 decimals; `0` when the base is 0.
`data.sms_performance.rates.delivered`	number	`delivered` as a percentage of `sent`.
`data.sms_performance.rates.link_clicked`	number	`link_clicked` as a percentage of `sent`.
`data.sms_performance.rates.failed`	number	`failed` as a percentage of `sent`.
`data.sms_performance.rates.sent`	number	`sent` as a percentage of the contacts with a valid phone number added in the period.
`data.audience`	object	Valid contacts added to the campaigns.
`data.audience.current_contacts`	integer	Valid contacts added in the period.
`data.audience.previous_contacts`	integer	Valid contacts added in the previous period of the same number of days, immediately before `start_date`.
`data.audience.change_percent`	number	Change from `previous_contacts` to `current_contacts`, in percent, 2 decimals. `0` when `previous_contacts` is 0.

Response payload

{
  "data": {
    "status": "success",
    "data": {
      "email_performance": {
        "sent": 0,
        "delivered": 0,
        "opened": 0,
        "clicked": 0,
        "unsubscribed": 0,
        "rates": {
          "delivered": 0,
          "opened": 0,
          "clicked": 0,
          "unsubscribed": 0,
          "sent": 0
        }
      },
      "sms_performance": {
        "sent": 0,
        "delivered": 0,
        "link_clicked": 0,
        "failed": 0,
        "rates": {
          "delivered": 0,
          "link_clicked": 0,
          "failed": 0,
          "sent": 0
        }
      },
      "audience": {
        "current_contacts": 0,
        "previous_contacts": 0,
        "change_percent": 0
      }
    }
  }
}

Examples

Success payload

January to September 2026, an account with no sends yet: see Response payload.

An account with activity:

{
  "data": {
    "status": "success",
    "data": {
      "email_performance": {
        "sent": 300,
        "delivered": 250,
        "opened": 220,
        "clicked": 200,
        "unsubscribed": 20,
        "rates": {
          "delivered": 83.33,
          "opened": 73.33,
          "clicked": 66.67,
          "unsubscribed": 6.67,
          "sent": 66.67
        }
      },
      "sms_performance": {
        "sent": 200,
        "delivered": 190,
        "link_clicked": 180,
        "failed": 10,
        "rates": {
          "delivered": 95,
          "link_clicked": 90,
          "failed": 5,
          "sent": 95
        }
      },
      "audience": {
        "current_contacts": 356,
        "previous_contacts": 356,
        "change_percent": 0
      }
    }
  }
}

Error payload

422 Dates missing

{
  "message": "The start date field is required. (and 1 more error)",
  "errors": {
    "start_date": [
      "The start date field is required."
    ],
    "end_date": [
      "The end date field is required."
    ]
  }
}

422 end_date before start_date

{
  "message": "The end date field must be a date after or equal to start date.",
  "errors": {
    "end_date": [
      "The end date field must be a date after or equal to start date."
    ]
  }
}

422 Location outside your tree

{
  "message": "The selected store id does not belong to your company hierarchy.",
  "errors": {
    "store_id": [
      "The selected store id does not belong to your company hierarchy."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Status	Meaning
`200`	The totals.
`401`	The token is missing, expired or invalid.
`422`	A date is missing or not `Y-m-d`, `end_date` is before `start_date`, or `store_id` is outside your tree.
`429`	More than 120 requests in a minute from this user.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/dashboard/metrics?start_date=2026-01-01&end_date=2026-09-30" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'