Reports API - Fields Reference

This article defines every metric, rate, and shared query parameter used by the Reports API. Use it as the glossary for the message activity list, the single-message and compare reports, the message contacts report, and the contact activity report; the account overview shares its error responses and unknown-parameter rule.

The Reports API returns email activity counts for the messages and contacts in your Envoke account. It is read-only and has five groups of endpoints, all on /v2:

Every message report uses the same ten metrics, defined once in this article, so the same message gives the same numbers in the list, in its single report, and in a comparison. Message id values are the same numbers as the id of the Message API, message folders (group_id) are managed with the Group API, and the tags and subscriptions used as filters with the Tag API and Subscription API. Contact id values are the same as the id of the Contact API. The account overview does not use the ten metrics: its contact counts describe the account now, and its twelve-month email block counts records, as the Database overview does, not distinct contacts.

The Reports API replaces the beta GET https://e1.envoke.com/v1/reports/emailActivityMetrics (beta reference). The two do not count the same way: the beta counts opens and bounces as records rather than distinct contacts, its revoked_consent misses one-click unsubscribes, its start_date and end_date filter activity as activity_from and activity_to do here, and it returns every value as a string.

Counts are read from a reporting copy of the database, so activity from the last few moments may not appear yet. There is no CSV format; every response is JSON.

All requests require HTTP Basic Auth using your API ID and API Key.

The ten metrics, in the order they appear in every response. Each is an integer count of distinct contacts.

The rates, returned only by the single-message and compare reports, are decimals rounded to four places:

Envoke records message activity as one record per message, event type, event sub-type, and contact. The sub-type is the detail of the event: the email client for an open, the link for a click, the reason for a bounce. A repeated event adds nothing: a contact who opens a message ten times in the same email client has one open record, and a contact who clicks the same link twice has one click record for that link. No count of repeated events exists, so the Reports API has no "total opens" or "total clicks" figure.

Every metric counts distinct contacts: a contact with at least one matching record counts once, however many sub-types they have. A contact who opened in two email clients counts once in opens; a contact who was deferred and then hard-bounced counts once in bounces.

Each metric is listed below with the event type and sub-type codes it reads, the same codes the Sent message report in Envoke uses. The Sent message report counts some rows differently: its Opens and Bounced rows count one per contact per sub-type, so they can be larger than opens and bounces. Each metric states exactly how it relates to the report row. The JSON paths refer to https://e1.envoke.com/messages/{id}/stats.json, the data behind that report.

Activity window. When activity_from or activity_to is given, every metric counts only the records made inside the window, by the time the activity happened (see Date parameters). A contact sent the message before the window and who opened it inside the window counts in opens but not in sends or delivered. delivered has its own windowed definition, so it is never negative.

Current-state blocks are null in a window. The single-message report's unsubscribe_reasons and polls describe contacts as they are now (the consent a contact holds today, the poll answer a contact holds today), not records made at a moment, so they cannot be limited to a window. When activity_from or activity_to is given, both are null rather than current figures beside windowed ones.

Integers, not strings. Counts and rates are JSON numbers. A rate or other decimal that is a whole value is written without a decimal point (1, 0), so read rates as floating-point numbers. IDs are strings ("2001"), as in the other Envoke APIs.

The number of contacts the message was handed off to for delivery. A contact sent the same automated message more than once counts once, because the send is recorded once per contact. Contacts selected but not sent (no consent, invalid address, unverified) are in skips, not here.

Today a contact counts as delivered when it was sent the message and has no bounce record of any kind, including a temporary deferral that was later delivered. Envoke has begun recording confirmed deliveries (type 7, sub-type 11); once those records cover past messages too, delivered will switch to counting them, with and without a window, and the change will be announced before it happens.

Inside an activity window, delivered counts only contacts the message was sent to inside the window, so it is never larger than the window's sends and never negative. A bounce counts against a contact whenever it arrived: a contact sent the message on the last day of the window whose bounce arrived the next day is not delivered. The window's sends minus its bounces is therefore not this figure: a message whose bounce arrived after a window that excludes its sends has sends 0, bounces 1, and delivered 0, where the Sent message report shows Delivered -1 for the same window.

Includes temporary deferrals (14), so a contact deferred and then delivered counts as bounced.

A contact can be in both hard_bounces and soft_bounces (for example, deferred and then hard-bounced), so the two can add up to more than bounces. Sub-type 13 is in neither; it has not been written for years and appears only on old messages.

Opens depend on images being loaded and include opens made automatically by mail privacy and security proxies (Apple Mail Privacy Protection, and the Gmail and Yahoo image proxies); opens counts them like any other open. The single-message report's email_clients block shows how many open records Envoke attributes to Apple Mail Privacy Protection (machine_open_records), counted as records, not contacts. A contact-level machine-opens metric may be added later.

Clicks are not limited to contacts who opened: a contact whose email client blocks images can click without an open being recorded, so click_to_open can be above 1 on a small message.

Includes contacts who revoked consent on the preferences page reached from the message, through its unsubscribe link, and through an email client's one-click unsubscribe button. A one-click unsubscribe on a message sent with a primary subscription removes the contact from that subscription and records only sub-type 30, not 11; the beta's revoked_consent misses those contacts and unsubscribes does not. Removing a subscription on the preferences page (5/17), spam reports, and consent changes made outside the preferences page (the Envoke app, the Contact API, imports) are not unsubscribes.

Contacts who were in the message's recipient list when it was sent but were not sent it. They are not in sends.

Rates appear in the rates object of the single-message and compare reports, never in the list. Each is a decimal, normally between 0 and 1 (0.4665 means 46.65%), rounded to four decimal places and returned as a JSON number, so a whole value appears as 1 or 0 without a decimal point, computed from the distinct-contact counts above for the same message and window, so inside an activity window the denominators are the window's sends, opens, and windowed delivered:

A rate whose denominator is 0 is null, not 0 (the Sent message report shows 0). Inside an activity window the numerator and the denominator need not be the same contacts: opens, clicks, bounces, and unsubscribes in the window can come from contacts sent the message before it, so open, click, bounce, and unsubscribe can be above 1, and a window that holds none of the message's sends gives null for every rate except click_to_open. A lifetime open or click rate can also be above 1 when opens or clicks were recorded for contacts with no send record (see opens).

Because opens counts distinct contacts and the Sent message report's Opens row counts contacts per email client, the API's open rate is less than or equal to the report's open rate. click_to_open can exceed 1 (see clicks).

Rows of the message activity list and the header of the single-message report describe the message with these fields:

sent_time is the value that sent_from and sent_to filter and that the list is sorted by.

The contacts behind each metric of one message are listed by the message contacts report (event=opened for opens, and so on).

Every time the Reports API returns (sent_time, last_send_time, last_open_time, last_click_time, first_open_time, first_click_time, event_time) is YYYY-MM-DD HH:MM:SS in your account's time zone, with no offset, and every date parameter is read in the same zone. The account time zone is the one set in your Envoke account preferences, for example America/Vancouver; daylight saving time applies. It is the zone the Message API uses for send_time, create_time, and modified_time and the zone the Envoke app shows, so the same moment has the same wall-clock time in all three.

The account overview is the exception: it returns no times, and its intervals use Envoke's server clock, as the Database overview does.

Envoke records the time of the first occurrence of each record: a contact's first open of a message in each email client, their first click on each link. A repeat open or click does not change any time.

Two pairs of optional parameters, used by different endpoints:

So sent_from=2026-05-01&sent_to=2026-05-31 lists the messages launched in May with their lifetime counts, and activity_from=2026-05-01&activity_to=2026-05-31 counts only May's activity.

Lists (the message activity list, the message contacts report, and the messages array of the contact report) page with limit and skip:

A limit or skip that is not a whole number returns HTTP 400 with Invalid 'limit': 'ten' or Invalid 'skip': 'abc', the same strings as the Message API. There is no page parameter, no fields or result_type, and no sort: the order is fixed, so pages never overlap. The one exception is the message contacts report, which takes fields and then lifts the cap to 10,000 (see fields and the 10,000 limit).

Each endpoint accepts only the parameters listed in its article. Any other parameter, including the beta's start_date, end_date, segment, and page, and the CRUD APIs' filter, sort, fields, and result_type, returns HTTP 400 with Parameter 'page' is not valid, naming the parameter. Only the message contacts report accepts fields.

Validation errors return HTTP 400 with the validation envelope. Every problem in the request is listed:

The validation strings shared by every endpoint:

Each endpoint's article lists its own further errors.

Query time limit and database errors. A report whose database query runs longer than 30 seconds is stopped, and the request fails with HTTP 400 and this body, which is also what any database error returns:

Narrow the request and try again: a shorter activity window, fewer messages or a smaller folder in a comparison, or a smaller page of contacts.

Path not found. A message or contact ID in the path that is not a number (/v2/reports/messages/abc) and any path that is not a Reports API endpoint return HTTP 404 with this body:

The body is JSON but is sent with Content-Type: text/html, as on the beta.

Authentication and limits. An invalid API ID or key returns 401 with the body {"success":false,"result_data":[],"result_text":"Invalid credentials"}, sent with Content-Type: text/html like the 404. A valid key on a closed or inactive account returns 403 with the JSON body {"success":false,"result_data":[],"result_text":"This account has been closed."}, or the same body with This account is not active. Exceeding your account's API limit returns 429 with success: false and a result_text naming the limit. The contact activity endpoints also return 403, with a JSON body, on an account restricted from seeing contact-level email activity; see Contact Activity errors. The message contacts report returns the same 403 for every event; see Message Contacts errors. The account overview is not restricted.

Not-found behaviour varies by endpoint:

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