Email request usage

Overview

See how many email requests each location plan has used.

Use this to watch usage or show it to a business.

You'll need an account or partner token; filter by account or location. With a Partner token, pass the account's company_id: without it the list is empty.

Returns one row per location plan, with its email request count. Allowances and overage aren't included.

Prerequisites

A bearer token. See Authentication.
With a Partner token: the account's id (company_id).

Base URL

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

Endpoint

GET /api/v1/solicitation/email-overage-summary

Authentication

Partner or Account token

company_id and store_id must be inside your own account tree; otherwise 422.
Without company_id, the rows are for the account of the user behind the token. A Partner token must pass an account's company_id, or the list is empty.

Rate limit

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

Request parameters

Parameter	In	Type	Required	Description
`company_id`	query	integer	No	The account to report on. Must be inside your account tree. Default: the account of the user behind the token.
`store_id`	query	integer	No	Only this location. Must be inside your account tree.
`search_field`	query	string	No	The field to search, used with `search_value`: `store_name` (also matches your location reference and client location id), `account_name`, `store_plan_status`, `store_plan_end` (a date) or `store_plan_id`. Other values are ignored.
`search_value`	query	string	No	The value to search for, without `<` or `>`. Names match part of the value; the other fields must match exactly.
`sort_field`	query	string	No	The field to sort by: `account_name`, `store_name`, `store_plan_id`, `store_plan_status`, `store_plan_end`, `email_sent_count`. Other values fall back to the location name.
`sort_by`	query	string	No	`asc` or `desc` (either case). Default `asc`.
`page`	query	integer	No	The page to return, from `1`. Default `1`.
`limit`	query	integer	No	Rows per page, `10`–`100`. Default `20`. Values below 10 are raised to 10; above 100 returns `422`.

Request body

None.

Request payload

None.

Response body

The payload is inside data: a page of location plans, with the paging fields beside it.

Field	Type	Description
`data`	array of objects	One row per location plan, sorted by location name by default. An empty array `[]` when none match.
`data[].id`	integer	The location plan's id (same as `store_plan_id`).
`data[].account_name`	string	The account's name.
`data[].store_name`	string	The location's name, followed by its client location id or your own reference when it has one.
`data[].store_plan_id`	integer	The location plan's id.
`data[].store_plan_status`	string	The location plan's status, e.g. `active` or `close`.
`data[].store_plan_end`	string or null	When the location plan ends (`Y-m-d H:i:s`), or `null`.
`data[].email_sent_count`	integer	Email review requests created under this location plan, whatever their status, including test sends. `0` when there are none.
`current_page`	integer	The page returned.
`per_page`	integer	Rows per page.
`total`	integer	Rows matching the filters, across all pages.
`last_page`	integer	The last page number.
`from`	integer or null	Position of the first row on this page, or `null` when the page is empty.
`to`	integer or null	Position of the last row on this page, or `null` when the page is empty.
`first_page_url`	string	URL of the first page.
`last_page_url`	string	URL of the last page.
`prev_page_url`	string or null	URL of the previous page, or `null`.
`next_page_url`	string or null	URL of the next page, or `null`.
`path`	string	The endpoint URL without the query string.
`links`	array of objects	Page links for a pager.
`links[].url`	string or null	The link's URL, or `null` when there is no such page.
`links[].label`	string	The link's label, e.g. `1` or `Next »`.
`links[].page`	integer or null	The page number, or `null`.
`links[].active`	boolean	`true` for the current page.

Response payload

{
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 14935,
        "account_name": "Acme Coffee",
        "store_name": "Acme Coffee - docs-test-loc-001",
        "store_plan_id": 14935,
        "store_plan_status": "active",
        "store_plan_end": "2026-10-31 23:59:59",
        "email_sent_count": 1
      },
      {
        "id": 14482,
        "account_name": "Acme Coffee",
        "store_name": "Acme Coffee - docs-test-loc-001",
        "store_plan_id": 14482,
        "store_plan_status": "close",
        "store_plan_end": "2026-09-30 23:59:59",
        "email_sent_count": 0
      },
      {
        "id": 14936,
        "account_name": "Acme Coffee",
        "store_name": "Acme Coffee - Circular Quay - Sydney",
        "store_plan_id": 14936,
        "store_plan_status": "active",
        "store_plan_end": "2026-10-31 23:59:59",
        "email_sent_count": 0
      },
      {
        "id": 14483,
        "account_name": "Acme Coffee",
        "store_name": "Acme Coffee - Circular Quay - Sydney",
        "store_plan_id": 14483,
        "store_plan_status": "close",
        "store_plan_end": "2026-09-30 23:59:59",
        "email_sent_count": 0
      }
    ],
    "first_page_url": "https://production-api.shoutaboutus.com/api/v1/solicitation/email-overage-summary?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://production-api.shoutaboutus.com/api/v1/solicitation/email-overage-summary?page=1",
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/solicitation/email-overage-summary?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "https://production-api.shoutaboutus.com/api/v1/solicitation/email-overage-summary",
    "per_page": 20,
    "prev_page_url": null,
    "to": 4,
    "total": 4
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Account outside your tree

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

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

422 limit above 100

{
  "message": "The limit field must not be greater than 100.",
  "errors": {
    "limit": [
      "The limit field must not be greater than 100."
    ]
  }
}

429 Too many requests

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

Status	Meaning
`200`	A page of location plans with their request counts, or an empty `data` array.
`401`	The token is missing, expired or invalid.
`422`	`company_id` or `store_id` doesn't exist or is outside your tree, or `limit` is above 100.
`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/solicitation/email-overage-summary?company_id=5994" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'