Email recipients and status

Overview

Get each email recipient with their status.

Use this to see who opened or clicked.

You'll need the campaign's id.

Returns one row per email request, newest first, 10 per page unless you set limit. Test sends are included.

Prerequisites

A bearer token. See Authentication.
The campaign's id (campaignId), from List campaigns.

Base URL

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

Endpoint

GET /api/v1/campaign/{campaignId}/recipients/email

Authentication

Account token

The campaign must belong to the caller's own company. Any other id, including a campaign of another account, returns 404 Campaign not found.

Rate limit

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

Request parameters

Parameter	In	Type	Required	Description
`campaignId`	path	integer	Yes	The campaign's id (digits only). It must belong to your own company.
`filter`	query	string	No	Only rows at this stage: `processed`, `pending`, `sent`, `delivered`, `opened`, `clicked`, `unsubscribed`, `failed`. `pending` and `failed` match the status; the others match rows that reached that step.
`search_field`	query	string	No	Field to search: `email`, `status`, `message_id`, `customer_name`. Leave it out to search all four.
`search_value`	query	string	No	Text to search for (contains), up to 255 characters.
`sort_field`	query	string	No	Column to sort by. Default `created_at`.
`sort_by`	query	string	No	Sort direction: `asc` or `desc` (either case). Default `desc`.
`limit`	query	integer	No	Rows per page, 10 to 100. Values below 10 are raised to 10; above 100 returns `422`. Default 10.
`page`	query	integer	No	Page number, from 1. Default 1.

Request body

None.

Request payload

None.

Response body

This endpoint returns a standard page object at the top level, not wrapped in the usual data object: the rows are in data, next to the paging fields. There is no meta object.

Field	Type	Description
`current_page`	integer	This page's number.
`data[]`	array of objects	The recipients on this page.
`data[].id`	integer	The email request's id.
`data[].status`	string	The request's status, e.g. `pending`, `sent` or `failed`.
`data[].sent_at`	string or null	When it was sent.
`data[].delivered_at`	string or null	When it was delivered.
`data[].opened_at`	string or null	When it was opened.
`data[].clicked_at`	string or null	When a link in it was clicked.
`data[].unsubscribed_at`	string or null	When the recipient unsubscribed.
`data[].failed_at`	string or null	When it failed.
`data[].unsubscribe_reason`	string or null	The reason given for unsubscribing.
`data[].failure_reason`	string or null	Why it failed.
`data[].metadata`	object or null	Extra sending details, e.g. `{"sent_via": "mandrill"}`.
`data[].created_at`	string	When the request was created.
`data[].email`	string	The recipient's email address.
`data[].message_id`	string or null	The email provider's message id, once sent.
`data[].campaign_audience_data_id`	integer or null	The id of the audience row (see `audience_data`).
`data[].next_follow_up_at`	string or null	When the next follow-up is due.
`data[].follow_up_count`	integer	Follow-ups sent so far.
`data[].parent_id`	integer or null	For a follow-up, the id of the original request.
`data[].unique_code`	string	Short code for this request, derived from its `id`.
`data[].audience_data`	object or null	The audience row (the uploaded customer) this request was sent to.
`data[].audience_data.id`	integer	The audience row's id.
`data[].audience_data.customer_name`	string or null	The customer's name.
`data[].audience_data.email`	string or null	The customer's email address.
`data[].audience_data.phone`	string or null	The customer's phone number.
`data[].audience_data.is_email_valid`	string	Whether the email address passed validation, e.g. `valid`, or `N/A` when there's none.
`data[].audience_data.is_phone_valid`	string	Whether the phone number passed validation, e.g. `valid`, or `N/A` when there's none.
`data[].audience_data.validation_status`	string	The row's overall validation status, e.g. `valid`.
`first_page_url`	string	URL of the first page.
`from`	integer or null	Position of the first row on this page; `null` when the page is empty.
`last_page`	integer	Number of the last page.
`last_page_url`	string	URL of the last page.
`links[]`	array of objects	Pager links: previous, each page number, next.
`links[].url`	string or null	URL of that page; `null` when there is no such page.
`links[].label`	string	Link text: a page number, `« Previous` or `Next »`.
`links[].page`	integer or null	Page number the link goes to; `null` when there is no such page.
`links[].active`	boolean	`true` for the current page.
`next_page_url`	string or null	URL of the next page; `null` on the last page.
`path`	string	URL of this endpoint, without query string.
`per_page`	integer	Rows per page (`limit`).
`prev_page_url`	string or null	URL of the previous page; `null` on the first page.
`to`	integer or null	Position of the last row on this page; `null` when the page is empty.
`total`	integer	Rows across all pages.

Response payload

{
  "current_page": 1,
  "data": [
    {
      "id": 24,
      "status": "sent",
      "sent_at": "2026-10-01T08:02:39.000000Z",
      "delivered_at": "2026-10-01T08:03:29.000000Z",
      "opened_at": "2026-10-01T08:03:29.000000Z",
      "clicked_at": null,
      "unsubscribed_at": null,
      "failed_at": null,
      "unsubscribe_reason": null,
      "failure_reason": null,
      "metadata": {
        "sent_via": "mandrill"
      },
      "created_at": "2026-10-01T08:02:35.000000Z",
      "email": "[email protected]",
      "message_id": "7b0172e7a6fe4b45a98332fd5b65dec4",
      "campaign_audience_data_id": 25,
      "next_follow_up_at": null,
      "follow_up_count": 0,
      "parent_id": null,
      "unique_code": "4xwu8",
      "audience_data": {
        "id": 25,
        "customer_name": "Jane Smith",
        "email": "[email protected]",
        "phone": null,
        "is_email_valid": "valid",
        "is_phone_valid": "N/A",
        "validation_status": "valid"
      }
    }
  ],
  "first_page_url": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/recipients/email?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/recipients/email?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "page": null,
      "active": false
    },
    {
      "url": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/recipients/email?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/campaign/4823/recipients/email",
  "per_page": 10,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Examples

Success payload

See Response payload.

Error payload

404 Campaign not found

{
  "message": "Campaign not found",
  "status": "error",
  "errors": []
}

422 Invalid filter

{
  "message": "The selected filter is invalid.",
  "errors": {
    "filter": [
      "The selected filter is invalid."
    ]
  }
}

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`	One page of recipients.
`401`	The token is missing, expired or invalid.
`404`	No campaign with that id in your company (`Campaign not found`).
`422`	A query value is not allowed: for example an unknown `filter`, `sort_field` or `search_field`, or `limit` above 100.
`429`	More than 60 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/4823/recipients/email?limit=10&page=1" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'

Updated 17 days ago

Did this page help you?