Reports API - Message Activity

Use the message activity list to retrieve the ten activity metrics for your messages, one row per message, filtered by message, folder, recipient list, type, and date.

Authentication is via HTTP Basic Auth using your API ID and API Key.

Returns a JSON array of rows, one per message, most recently sent first. Each row describes the message and gives its ten metrics as integers. When nothing matches, the response is [].

The list has no rates and no breakdowns; for those, request the message's single report.

By default the list includes:

type=campaign or type=automated narrows the list to one of the two. include_in_progress=1 also includes campaigns that have started sending but are not finished (status AB test in progress, Queuing, or Sending). Their numbers change from one request to the next until the send completes, and an A/B test still in its test phase shows only the contacts sent so far.

Drafts, scheduled messages that have not started, messages of the Transactional status, and deleted or hidden messages (a message hidden or deleted in the app, stored with visible = 0) are never included. An automated message whose sequence is transactional has the Nurture status and is included like any automated message.

A message is listed when it matches every filter, whether or not it has any activity: a message sent to nobody, or one with nothing recorded inside the activity window, appears with every count 0. When an activity window is given, messages launched after activity_to are left out, since nothing can have happened to them yet.

A/B tests. An A/B test is one message with one row. has_variants is true, subject is null for a subject-line test (each version's subject is in the single report), and the counts are those of all its versions together, including the contacts sent the winning version after the test. The versions are never listed as rows; their own counts are in the variants of the single-message report.

The filters combine with AND. Any other parameter returns HTTP 400 (Parameter 'segment' is not valid); see Unknown parameters.

tag_id, segment_id, and subscription_id select messages by the list recorded on the message when it was sent, not by the contacts who are on that list today. They match the same values the Message API returns in recipient_tag, recipient_segment, and recipient_subscription for the message:

A message sent to several tags at once is recorded against an internal segment that no API returns, so it matches neither tag_id for one of those tags nor any segment_id. Automated messages are usually not sent to a list and match none of the three.

Names in the rows, IDs in the filters. recipient_subscription, recipient_tag, and recipient_segment in the rows are the names of the lists recorded on the message, while the filters tag_id, subscription_id, and segment_id take IDs. The IDs and current names of tags and subscriptions come from GET https://e1.envoke.com/v2/tags (Tag API) and GET https://e1.envoke.com/v2/subscriptions (Subscription API); segment IDs come from the segments in the Envoke app. A message whose list was deleted since it was sent can still show the list's name, but the deleted list is no longer returned by those APIs, so there is no ID to filter it by.

sent_from and sent_to choose which messages are listed, by sent_time. activity_from and activity_to choose which activity is counted. They can be combined:

For an automated message sent_time is the date it was set up or last activated, so sent_from and sent_to select automated messages by that date, not by when contacts received them. To report on what an automated message sent in a period, use message_id with activity_from and activity_to.

Inside an activity window delivered counts the contacts sent the message inside the window who have no bounce for it, so it is never negative and is not the window's sends − bounces; see delivered.

Rows are ordered by sent_time, newest first, and then by id, highest first, so messages launched in the same second always come back in the same order and pages never overlap. Messages with no sent_time come last. The order cannot be changed, and the order of message_id[] values in the request is not kept.

The response does not say how many rows exist in all. To read every row, request pages with skip until one returns fewer than limit rows.

See Messages in the fields reference for subject, type, and sent_time in detail.

Invalid parameters return HTTP 400 with the validation envelope (see Error Responses). Besides the shared date, limit, skip, and unknown-parameter errors, the list returns:

A filter value that is a whole number but matches nothing (an unknown folder, a tag in another account) is not an error: the response is [].

The rows come back newest first, not in the order the IDs were given.

Response (2001 was sent in April; only its May activity is counted, so sends is 0 and so is delivered, which counts only contacts sent the message in May):

Response:

The rows include the messages filed in the folder's subfolders.

Response (every metric is available whatever the message's age; only the single report's email_clients is null for messages sent before June 2022):

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

For code examples and interactive testing, visit api.envoke.com.