{ "openapi": "3.1.0", "info": { "title": "Envoke Reports API", "version": "2.0.0", "description": "Read-only email activity reports for the messages and contacts in an Envoke account: a per-message activity list, a full single-message report, a comparison of several messages or a folder, the contacts behind one message's metrics, and a contact's activity. Points a client must know: (1) Every metric is an integer count of distinct contacts; Envoke stores one activity record per message, event type, sub-type and contact, so there are no total-opens or total-clicks figures. The ten metrics are sends, delivered, bounces, hard_bounces, soft_bounces, opens, clicks, unsubscribes, spam_complaints and skips. delivered is sends minus bounces for lifetime counts and, inside an activity window, the contacts sent the message in the window with no bounce for it, so it is never negative. (2) Rates (delivered, open, click, click_to_open, bounce, unsubscribe) appear only on the single-message and compare reports, as decimals rounded to four places (JSON numbers, so a whole value is 1 or 0 without a decimal point), null when the denominator is 0. (3) Two date pairs: sent_from/sent_to choose messages by send time; activity_from/activity_to choose which activity records are counted. Formats YYYY-MM-DD or YYYY-MM-DD HH:MM:SS only, years 1970 to 2999, read in the account's time zone, as the Message API; returned times use the same zone. (4) Parameters are flat and named; arrays use name[]=; any other parameter is a 400 `Parameter '{name}' is not valid`. There is no filter[], sort, fields, result_type or page, except that the message contacts report accepts fields. group_id includes subfolders. (5) Lists are bare arrays, limit default 10 and cap 100, skip, fixed order sent_time descending then id descending, no total. The message contacts report orders by event_time then contact id, both descending, and lifts the cap to 10,000 when fields is given, as the Contact API does. (6) A single message or contact that is not found returns [] with 200; compare with an unknown message id returns 400 listing each id. Validation errors use HTTP 400 and the envelope `Validation failed, see 'result_data' -> 'errors'`. A report whose database query runs longer than 30 seconds, and any database error, returns HTTP 400 `{\"success\": false, \"result_data\": [], \"result_text\": \"Invalid request\"}`; narrow the window or the set and retry. Invalid credentials return 401, a closed or inactive account 403, the API limit 429. The contact activity endpoints and the message contacts report also return 403 `Contact-level email activity is not available on this account` on accounts restricted from contact-level email activity." }, "servers": [ { "url": "https://e1.envoke.com/v2", "description": "Production" } ], "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Message activity", "description": "Activity metrics per message (list)." }, { "name": "Message stats", "description": "Full report for one message, and comparisons of several messages or a folder." }, { "name": "Message contacts", "description": "The contacts behind one message's metrics (drill-down)." }, { "name": "Contact activity", "description": "One contact's email activity, by id, email or remote ID." } ], "paths": { "/reports/messages": { "get": { "tags": [ "Message activity" ], "operationId": "listMessageActivity", "summary": "List activity metrics per message", "description": "One row per message with the ten metrics as integers, newest sent_time first then highest id (fixed order). Includes sent campaigns and automated messages; `type` narrows, `include_in_progress=1` adds campaigns still sending; drafts, scheduled, Transactional-status, and deleted or hidden messages never appear (an automated message whose sequence is transactional is included). A message is listed when it matches every filter, with zeros when it has no activity; with an activity window, messages launched after `activity_to` are left out. A/B tests are one row with `has_variants: true` and, for a subject-line test, `subject: null`. Filters combine with AND. Unknown parameters give `Parameter '{name}' is not valid`.", "parameters": [ { "name": "message_id", "in": "query", "description": "One message ID (`message_id=2001`) or several (`message_id[]=2001&message_id[]=2004`). Not a whole number: `Invalid 'message_id': '{value}'`.", "schema": { "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } } ] }, "example": 2001 }, { "name": "group_id", "in": "query", "description": "One message folder ID or several (`group_id[]=`). Messages in the folder or in any of its subfolders, at any depth, are included (the beta's message_group_id took direct members only).", "schema": { "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" } } ] }, "example": 31 }, { "name": "tag_id", "in": "query", "description": "Only messages whose recipient_tag is this tag. Takes the tag's ID (from `GET /v2/tags`), not the name the row shows. One value (`Parameter 'tag_id' accepts one value`).", "schema": { "type": "integer" }, "example": 512 }, { "name": "segment_id", "in": "query", "description": "Only messages whose recipient_segment is this segment. Takes the segment's ID (from the segments in the Envoke app), not the name the row shows. One value.", "schema": { "type": "integer" }, "example": 77 }, { "name": "subscription_id", "in": "query", "description": "Only messages whose recipient_subscription is this subscription. Takes the subscription's ID (from `GET /v2/subscriptions`), not the name the row shows. One value.", "schema": { "type": "integer" }, "example": 514 }, { "name": "type", "in": "query", "description": "`campaign` or `automated`; both by default. Otherwise `Invalid 'type': '{value}' (possible values: 'campaign', 'automated')`.", "schema": { "type": "string", "enum": [ "campaign", "automated" ] }, "example": "automated" }, { "name": "include_in_progress", "in": "query", "description": "`1` adds campaigns still sending (AB test in progress, Queuing, Sending); their numbers change until the send completes. Otherwise `Invalid 'include_in_progress': '{value}' (possible values: '0', '1')`.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "example": 1 }, { "$ref": "#/components/parameters/SentFrom" }, { "$ref": "#/components/parameters/SentTo" }, { "$ref": "#/components/parameters/ActivityFrom" }, { "$ref": "#/components/parameters/ActivityTo" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Skip" } ], "responses": { "200": { "description": "Rows, or `[]` when nothing matches.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MessageActivityRow" } }, "examples": { "array": { "summary": "One row", "value": [ { "id": "2001", "name": "Spring Season Announcement", "subject": "Our spring season is here, {fname}", "type": "campaign", "sent_time": "2026-04-15 10:00:00", "recipient_subscription": "Season News", "recipient_tag": "", "recipient_segment": "", "has_variants": false, "sends": 412, "delivered": 403, "bounces": 9, "hard_bounces": 5, "soft_bounces": 4, "opens": 188, "clicks": 57, "unsubscribes": 4, "spam_complaints": 1, "skips": 6 } ] }, "empty": { "summary": "Nothing matches", "value": [] } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/messages/{id}": { "get": { "tags": [ "Message stats" ], "operationId": "getMessageStats", "summary": "Get the full report for one message", "description": "Totals, rates, bounce and preference-change breakdowns, links, email clients, unsubscribe reasons, polls and A/B variants for one message. Accepts only `activity_from` and `activity_to`; with either, `unsubscribe_reasons` and `polls` are `null` because they describe contacts as they are now. `variants` is always included when `has_variants` is true; no parameter requests or suppresses it. It is `[]` when the message's A/B block no longer exists. A message that does not exist, belongs to another account, is deleted, or has not started sending returns `[]`.", "parameters": [ { "$ref": "#/components/parameters/MessageId" }, { "$ref": "#/components/parameters/ActivityFrom" }, { "$ref": "#/components/parameters/ActivityTo" } ], "responses": { "200": { "description": "The report, or `[]`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MessageStats" }, { "$ref": "#/components/schemas/EmptyResult" } ] }, "examples": { "report": { "summary": "A message", "value": { "id": "2001", "name": "Spring Season Announcement", "subject": "Our spring season is here, {fname}", "type": "campaign", "sent_time": "2026-04-15 10:00:00", "has_variants": false, "totals": { "sends": 412, "delivered": 403, "bounces": 9, "hard_bounces": 5, "soft_bounces": 4, "opens": 188, "clicks": 57, "unsubscribes": 4, "spam_complaints": 1, "skips": 6 }, "rates": { "delivered": 0.9782, "open": 0.4665, "click": 0.1414, "click_to_open": 0.3032, "bounce": 0.0218, "unsubscribe": 0.0097 }, "bounces": [ { "type": "hard_bounce", "label": "Hard bounce", "contacts": 3 }, { "type": "soft_bounce", "label": "Soft bounce", "contacts": 2 }, { "type": "deferred", "label": "Temporarily deferred", "contacts": 1 }, { "type": "rejected", "label": "Rejected", "contacts": 0 }, { "type": "invalid_address", "label": "Invalid email address", "contacts": 2 }, { "type": "other", "label": "Other", "contacts": 1 } ], "preference_changes": [ { "type": "revoked_consent", "label": "Revoked consent", "contacts": 3 }, { "type": "one_click_unsubscribe", "label": "One-click unsubscribe", "contacts": 2 }, { "type": "spam_reported", "label": "Spam reported", "contacts": 1 }, { "type": "subscription_changed", "label": "Subscription changed", "contacts": 2 }, { "type": "language_changed", "label": "Language changed", "contacts": 1 }, { "type": "express_consent_granted", "label": "Express consent granted", "contacts": 0 } ], "links": [ { "id": "88121", "url": "https://example.org/season", "title": "See the full season", "type": "link", "clicks": 41 }, { "id": "88122", "url": "https://example.org/tickets/season-pass", "title": "Buy a season pass", "type": "link", "clicks": 22 }, { "id": "88124", "url": "", "title": "Envoke Preferences / Unsubscribe", "type": "pref", "clicks": 6 }, { "id": "88123", "url": "", "title": "Envoke View Message in Browser", "type": "view", "clicks": 4 } ], "email_clients": { "known_opens": 196, "machine_open_records": 52, "by_app": [ { "name": "Apple Mail", "opens": 74 }, { "name": "Gmail", "opens": 61 }, { "name": "Outlook", "opens": 38 }, { "name": "Yahoo", "opens": 6 }, { "name": "Other", "opens": 17 } ] }, "unsubscribe_reasons": [ { "reason": "no_longer_interested", "contacts": 1 }, { "reason": "too_many_emails", "contacts": 2 } ], "polls": [], "variants": [] } }, "empty": { "summary": "Not found", "value": [] } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/messages/compare": { "get": { "tags": [ "Message stats" ], "operationId": "compareMessageStats", "summary": "Compare several messages or a folder", "description": "Totals and rates per message plus a combined block whose totals are distinct contacts across the set. Give exactly one of `message_id` (one or more, at most 100; a repeated ID counts once) or `group_id` (one folder, subfolders included). With an activity window, messages launched after `activity_to` are left out of the set, as the list leaves them out; a `message_id` launched later is dropped without an error. Errors: `One of the parameters 'message_id' or 'group_id' must be provided`, `Only one of the parameters 'message_id' or 'group_id' may be provided`, `No message found for 'message_id': {id}` (one per unknown id, including messages in other accounts, deleted, or not sent), `No message group found for 'group_id': {id}`, `Too many messages to compare: {n} (maximum 100)`.", "parameters": [ { "name": "message_id", "in": "query", "description": "One or more message IDs (`message_id[]=2001&message_id[]=2004`), each a sent campaign or automated message in the account. At most 100; a repeated ID counts once.", "schema": { "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "type": "integer" }, "maxItems": 100 } ] }, "example": [ 2001, 2004 ] }, { "name": "group_id", "in": "query", "description": "One message folder ID; every sent campaign and automated message filed in it or in any of its subfolders, at any depth.", "schema": { "type": "integer" }, "example": 31 }, { "$ref": "#/components/parameters/ActivityFrom" }, { "$ref": "#/components/parameters/ActivityTo" } ], "responses": { "200": { "description": "The comparison.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" }, "examples": { "two": { "summary": "Two messages", "value": { "messages": [ { "id": "2004", "name": "Pirates Opening Night", "sent_time": "2026-05-14 09:30:00", "totals": { "sends": 386, "delivered": 379, "bounces": 7, "hard_bounces": 4, "soft_bounces": 3, "opens": 201, "clicks": 64, "unsubscribes": 2, "spam_complaints": 0, "skips": 3 }, "rates": { "delivered": 0.9819, "open": 0.5303, "click": 0.1689, "click_to_open": 0.3184, "bounce": 0.0181, "unsubscribe": 0.0052 } }, { "id": "2001", "name": "Spring Season Announcement", "sent_time": "2026-04-15 10:00:00", "totals": { "sends": 412, "delivered": 403, "bounces": 9, "hard_bounces": 5, "soft_bounces": 4, "opens": 188, "clicks": 57, "unsubscribes": 4, "spam_complaints": 1, "skips": 6 }, "rates": { "delivered": 0.9782, "open": 0.4665, "click": 0.1414, "click_to_open": 0.3032, "bounce": 0.0218, "unsubscribe": 0.0097 } } ], "combined": { "message_count": 2, "totals": { "sends": 702, "delivered": 686, "bounces": 16, "hard_bounces": 9, "soft_bounces": 7, "opens": 331, "clicks": 108, "unsubscribes": 6, "spam_complaints": 1, "skips": 9 }, "rates": { "delivered": 0.9772, "open": 0.4825, "click": 0.1574, "click_to_open": 0.3263, "bounce": 0.0228, "unsubscribe": 0.0085 } } } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/messages/{id}/contacts": { "get": { "tags": [ "Message contacts" ], "operationId": "listMessageContacts", "summary": "List the contacts behind one message's metric", "description": "One row per distinct contact with the event for the message: id, email, remote_id, event_time, count. Each event lists the contacts its metric counts, so the rows equal the single-message report's totals for the same window, less contacts deleted since; a message with an anonymous poll leaves every poll-answer click out of clicked. not_opened and not_clicked are the sent contacts minus the opened or clicked contacts, bounced contacts included (event_time null). Ordered by event_time descending then contact id descending (negative events by id descending). Answers for the same messages as the single-message report; a message that is not found returns []. Flat parameters, each taking one value except bounce_type, which accepts an array; any other parameter is a 400 `Parameter '{name}' is not valid`. On an account restricted from contact-level email activity, returns 403 for every event before checking parameters.", "parameters": [ { "$ref": "#/components/parameters/MessageId" }, { "$ref": "#/components/parameters/Event" }, { "$ref": "#/components/parameters/LinkId" }, { "$ref": "#/components/parameters/BounceType" }, { "$ref": "#/components/parameters/ActivityFrom" }, { "$ref": "#/components/parameters/ActivityTo" }, { "$ref": "#/components/parameters/ContactFields" }, { "$ref": "#/components/parameters/ContactsLimit" }, { "$ref": "#/components/parameters/Skip" } ], "responses": { "200": { "description": "The rows, or `[]`.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MessageContactRow" } }, "examples": { "opened": { "summary": "event=opened", "value": [ { "id": "1008", "email": "p.nguyen@example.org", "remote_id": "MRCT-0501", "event_time": "2026-05-16 19:44:02", "count": 2 }, { "id": "1005", "email": "l.ferreira@example.org", "remote_id": "", "event_time": "2026-05-15 07:12:55", "count": 1 }, { "id": "1004", "email": "maya.chen@example.org", "remote_id": "MRCT-0412", "event_time": "2026-05-14 12:02:44", "count": 1 } ] }, "ids": { "summary": "event=not_opened&fields=id (sent, did not open)", "value": [ { "id": "1006" }, { "id": "1003" }, { "id": "1002" } ] }, "empty": { "summary": "Not found, or no contact has the event", "value": [] } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "success": false, "result_data": { "errors": [ "Parameter 'event' must be provided", "Invalid 'activity_from': '05/14/2026' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)" ] }, "result_text": "Validation failed, see 'result_data' -> 'errors'" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ContactForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/contacts/{id}": { "get": { "tags": [ "Contact activity" ], "operationId": "getContactActivity", "summary": "Get one contact's email activity", "description": "The contact, a summary of message counts, and the messages the contact was sent (newest first, paged with limit and skip; summary is never paged). A contact that does not exist, belongs to another account, or is deleted returns `[]`. On an account restricted from contact-level email activity, returns 403 `Contact-level email activity is not available on this account`.", "parameters": [ { "$ref": "#/components/parameters/ContactId" }, { "$ref": "#/components/parameters/ActivityFrom" }, { "$ref": "#/components/parameters/ActivityTo" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Skip" } ], "responses": { "200": { "description": "The activity, or `[]`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactActivity" }, { "$ref": "#/components/schemas/EmptyResult" } ] }, "examples": { "activity": { "summary": "A contact", "value": { "contact": { "id": "1004", "email": "maya.chen@example.org", "remote_id": "MRCT-0412" }, "summary": { "sends": 3, "delivered": 3, "bounces": 0, "opens": 2, "clicks": 1, "unsubscribes": 0, "last_send_time": "2026-05-14 09:31:07", "last_open_time": "2026-05-14 12:02:44", "last_click_time": "2026-05-14 12:03:10" }, "messages": [ { "id": "2004", "name": "Pirates Opening Night", "sent_time": "2026-05-14 09:31:07", "delivered": true, "bounced": false, "opened": true, "first_open_time": "2026-05-14 12:02:44", "opens": 1, "clicked": true, "clicks": 1, "links": [ { "id": "88125", "url": "https://example.org/tickets/pirates", "first_click_time": "2026-05-14 12:03:10" } ], "unsubscribed": false } ] } }, "empty": { "summary": "Not found", "value": [] } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ContactForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports/contacts": { "get": { "tags": [ "Contact activity" ], "operationId": "findContactActivity", "summary": "Find a contact's email activity by email or remote ID", "description": "The same object as getContactActivity for the contact found by exactly one of `email` or `remote_id` (the whole value, compared as the Contact API's `filter[email]` and `filter[remote_id]` compare it; letter case does not matter). No match returns `[]`. Errors: `One of the parameters 'email' or 'remote_id' must be provided`, `Only one of the parameters 'email' or 'remote_id' may be provided`, `Invalid 'email': ''` (an empty value; also for `remote_id`), `More than one contact found for 'remote_id': '{value}'` (or `'email'`). On an account restricted from contact-level email activity, returns 403 `Contact-level email activity is not available on this account`.", "parameters": [ { "name": "email", "in": "query", "description": "The contact's email address, URL-encoded. Not with remote_id.", "schema": { "type": "string" }, "example": "maya.chen@example.org" }, { "name": "remote_id", "in": "query", "description": "The contact's remote ID. Not with email. More than one matching contact is a 400.", "schema": { "type": "string" }, "example": "MRCT-0412" }, { "$ref": "#/components/parameters/ActivityFrom" }, { "$ref": "#/components/parameters/ActivityTo" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Skip" } ], "responses": { "200": { "description": "The activity, or `[]`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactActivity" }, { "$ref": "#/components/schemas/EmptyResult" } ] }, "examples": { "activity": { "summary": "Found by remote_id", "value": { "contact": { "id": "1004", "email": "maya.chen@example.org", "remote_id": "MRCT-0412" }, "summary": { "sends": 3, "delivered": 3, "bounces": 0, "opens": 2, "clicks": 1, "unsubscribes": 0, "last_send_time": "2026-05-14 09:31:07", "last_open_time": "2026-05-14 12:02:44", "last_click_time": "2026-05-14 12:03:10" }, "messages": [ { "id": "2004", "name": "Pirates Opening Night", "sent_time": "2026-05-14 09:31:07", "delivered": true, "bounced": false, "opened": true, "first_open_time": "2026-05-14 12:02:44", "opens": 1, "clicked": true, "clicks": 1, "links": [ { "id": "88125", "url": "https://example.org/tickets/pirates", "first_click_time": "2026-05-14 12:03:10" } ], "unsubscribed": false } ] } }, "empty": { "summary": "No match", "value": [] } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ContactForbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic Auth. Use your API ID as the username and API Key as the password. See https://developers.envoke.com/guides/authentication/." } }, "parameters": { "SentFrom": { "name": "sent_from", "in": "query", "description": "Only messages whose sent_time is on or after this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'sent_from': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.", "schema": { "type": "string" }, "example": "2026-04-01" }, "SentTo": { "name": "sent_to", "in": "query", "description": "Only messages whose sent_time is on or before this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'sent_to': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.", "schema": { "type": "string" }, "example": "2026-04-30" }, "ActivityFrom": { "name": "activity_from", "in": "query", "description": "Count only activity records made on or after this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'activity_from': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.", "schema": { "type": "string" }, "example": "2026-05-01" }, "ActivityTo": { "name": "activity_to", "in": "query", "description": "Count only activity records made on or before this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'activity_to': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.", "schema": { "type": "string" }, "example": "2026-05-31 23:59:59" }, "Limit": { "name": "limit", "in": "query", "description": "Maximum number of items. Default 10, hard cap 100 (larger values return 100); `0`, a value of zeros such as `00`, or empty gives the default; `limit=1` still returns an array. Not a whole number: `Invalid 'limit': '{value}'`.", "schema": { "type": "integer", "minimum": 0, "default": 10 }, "example": 25 }, "Skip": { "name": "skip", "in": "query", "description": "Number of items to skip. Not a whole number: `Invalid 'skip': '{value}'`.", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 25 }, "MessageId": { "name": "id", "in": "path", "required": true, "description": "The Envoke message ID. A non-numeric value returns 404.", "schema": { "type": "integer", "minimum": 1 }, "example": 2004 }, "ContactId": { "name": "id", "in": "path", "required": true, "description": "The Envoke contact ID (Contact API `id`). A non-numeric value returns 404.", "schema": { "type": "integer", "minimum": 1 }, "example": 1004 }, "Event": { "name": "event", "in": "query", "required": true, "description": "Which contacts to list. sent: type 1 (rows = totals.sends). delivered: sent with no bounce record for the message; in an activity window, sent inside the window with no bounce at any time (rows = totals.delivered). bounced: any type 2, or the bounce_type reasons (rows = totals.bounces). opened: type 3 (rows = totals.opens). clicked: type 4, or the link_id link (rows = totals.clicks, except that a message with an anonymous poll leaves out every poll-answer click). unsubscribed: 5/11 or 5/30 (rows = totals.unsubscribes). spam_reported: 5/12 or 5/13 (rows = totals.spam_complaints). skipped: type 6 (rows = totals.skips). not_opened and not_clicked: the sent contacts minus the opened (or clicked) contacts, bounced contacts included, as the segment conditions \"didn't open\" and \"didn't click\" (lifetime, not_opened is sent minus the sent contacts who opened; Envoke can record an open or click for a contact with no send record, who is in opened but not in sent or not_opened, so not_opened + opened can exceed sent). Contacts deleted since are not listed. Missing: `Parameter 'event' must be provided`; other values: `Invalid 'event': '{value}' (possible values: 'sent', 'delivered', 'bounced', 'opened', 'clicked', 'unsubscribed', 'spam_reported', 'skipped', 'not_opened', 'not_clicked')`.", "schema": { "type": "string", "enum": [ "sent", "delivered", "bounced", "opened", "clicked", "unsubscribed", "spam_reported", "skipped", "not_opened", "not_clicked" ] }, "example": "opened" }, "LinkId": { "name": "link_id", "in": "query", "description": "With event=clicked, only contacts who clicked this link; with event=not_clicked, sent contacts who did not click it. One tracked link of the message (the id in the single-message report's links); poll answers are not accepted. Not a whole number: `Invalid 'link_id': '{value}'`; not a link of this message: `Invalid 'link_id': '{value}'` (checked only when the message is found); with another event: `Parameter 'link_id' requires event 'clicked' or 'not_clicked'`.", "schema": { "type": "integer", "minimum": 1 }, "example": 88125 }, "BounceType": { "name": "bounce_type", "in": "query", "description": "With event=bounced, only contacts with one of these bounce reasons, the type keys of the single-message report's bounces block. One value or several (`bounce_type[]=hard_bounce&bounce_type[]=invalid_address` lists the contacts of hard_bounces). Other values: `Invalid 'bounce_type': '{value}' (possible values: 'hard_bounce', 'soft_bounce', 'deferred', 'rejected', 'invalid_address', 'other')`; with another event: `Parameter 'bounce_type' requires event 'bounced'`.", "schema": { "oneOf": [ { "type": "string", "enum": [ "hard_bounce", "soft_bounce", "deferred", "rejected", "invalid_address", "other" ] }, { "type": "array", "items": { "type": "string", "enum": [ "hard_bounce", "soft_bounce", "deferred", "rejected", "invalid_address", "other" ] } } ] }, "example": "hard_bounce" }, "ContactFields": { "name": "fields", "in": "query", "description": "Comma-separated row fields to return, from id, email, remote_id, event_time and count; returned in that order whatever the order given. Lifts the limit: with fields and no limit, up to 10,000 rows; a limit above 100 is honoured up to 10,000, larger values return 10,000. Applies to every event. Other names, or an empty value: `Invalid 'fields': '{name}' (possible values: 'id', 'email', 'remote_id', 'event_time', 'count')`.", "schema": { "type": "string" }, "example": "id,email" }, "ContactsLimit": { "name": "limit", "in": "query", "description": "Maximum number of rows. Default 10, cap 100 (larger values return 100); with fields, default 10,000 and cap 10,000. `0` or empty gives the default (10,000 with fields); a value of several zeros such as `00` gives 10, with or without fields; `limit=1` still returns an array. Not a whole number: `Invalid 'limit': '{value}'`.", "schema": { "type": "integer", "minimum": 0, "default": 10 }, "example": 100 } }, "schemas": { "Metrics": { "type": "object", "description": "The ten metrics, each a count of distinct contacts, in this order. Envoke stores one activity record per message, event type, sub-type and contact, so no count of repeated events exists.", "required": [ "sends", "delivered", "bounces", "hard_bounces", "soft_bounces", "opens", "clicks", "unsubscribes", "spam_complaints", "skips" ], "properties": { "sends": { "type": "integer", "description": "Distinct contacts with a send record (type 1, any sub-type). Equals the Sent row of the Sent message report.", "examples": [ 412 ] }, "delivered": { "type": "integer", "description": "Lifetime: `sends` − `bounces`; greater than or equal to the report's Delivered row. Inside an activity window: distinct contacts with a send record in the window and no bounce record for the message at any time, so never negative and never above the window's `sends` (the report's Delivered row for the same window can be negative). Will switch to confirmed delivery records (type 7 sub-type 11) once they are backfilled; the change will be announced.", "examples": [ 403 ] }, "bounces": { "type": "integer", "description": "Distinct contacts with any bounce record (type 2, sub-types 10, 11, 12, 13, 14, 15, 16), including temporary deferrals. Less than or equal to the report's Bounced row, which counts one per contact per bounce sub-type.", "examples": [ 9 ] }, "hard_bounces": { "type": "integer", "description": "Distinct contacts with a hard bounce (2/12) or an invalid address (2/16).", "examples": [ 5 ] }, "soft_bounces": { "type": "integer", "description": "Distinct contacts with an SMTP error (2/10), soft bounce (2/11), temporary deferral (2/14) or rejection (2/15). A contact can be in both hard_bounces and soft_bounces.", "examples": [ 4 ] }, "opens": { "type": "integer", "description": "Distinct contacts with any open record (type 3, any sub-type). Less than or equal to the report's Opens row, which counts one per contact per email client. Usually no larger than sends, but can be: Envoke records opens for contacts with no send record for the message.", "examples": [ 188 ] }, "clicks": { "type": "integer", "description": "Distinct contacts with any click record (type 4, any tracked link, including view-online, preferences and poll answers). Equals the report's Clicks row.", "examples": [ 57 ] }, "unsubscribes": { "type": "integer", "description": "Distinct contacts with a revoked-consent (5/11) or one-click unsubscribe (5/30) record. Between the larger of and the sum of the report's Revoked consent and One-click unsubscribe rows.", "examples": [ 4 ] }, "spam_complaints": { "type": "integer", "description": "Distinct contacts with a spam report through Envoke (5/12) or from their mailbox provider (5/13).", "examples": [ 1 ] }, "skips": { "type": "integer", "description": "Distinct contacts selected but not sent the message (type 6, any sub-type). Less than or equal to the report's Skipped row.", "examples": [ 6 ] } } }, "Rates": { "type": "object", "description": "The six rates, decimals rounded to four places and returned as JSON numbers (a whole value is 1 or 0 without a decimal point), computed from the Metrics of the same message and window. Normally between 0 and 1; inside an activity window open, click, bounce and unsubscribe can exceed 1 because activity in the window can come from contacts sent the message before it, and a lifetime open or click rate can exceed 1 when opens or clicks were recorded for contacts with no send record. Only on the single-message and compare reports.", "required": [ "delivered", "open", "click", "click_to_open", "bounce", "unsubscribe" ], "properties": { "delivered": { "type": [ "number", "null" ], "description": "`delivered` ÷ `sends`, rounded to four decimals; `null` when the denominator is 0.", "examples": [ 0.9782 ] }, "open": { "type": [ "number", "null" ], "description": "`opens` ÷ `delivered`, rounded to four decimals; `null` when the denominator is 0.", "examples": [ 0.4665 ] }, "click": { "type": [ "number", "null" ], "description": "`clicks` ÷ `delivered`, rounded to four decimals; `null` when the denominator is 0.", "examples": [ 0.1414 ] }, "click_to_open": { "type": [ "number", "null" ], "description": "`clicks` ÷ `opens`, rounded to four decimals; can exceed 1 because a click needs no recorded open; `null` when `opens` is 0.", "examples": [ 0.3032 ] }, "bounce": { "type": [ "number", "null" ], "description": "`bounces` ÷ `sends`, rounded to four decimals; `null` when `sends` is 0.", "examples": [ 0.0218 ] }, "unsubscribe": { "type": [ "number", "null" ], "description": "`unsubscribes` ÷ `sends`, rounded to four decimals; `null` when `sends` is 0.", "examples": [ 0.0097 ] } } }, "MessageActivityRow": { "type": "object", "description": "One row of the message activity list: the message and its ten metrics.", "required": [ "id", "name", "subject", "type", "sent_time", "recipient_subscription", "recipient_tag", "recipient_segment", "has_variants", "sends", "delivered", "bounces", "hard_bounces", "soft_bounces", "opens", "clicks", "unsubscribes", "spam_complaints", "skips" ], "properties": { "id": { "type": "string", "description": "Envoke message ID; the Message API `id`.", "examples": [ "2001" ] }, "name": { "type": "string", "description": "The message's internal name.", "examples": [ "Spring Season Announcement" ] }, "subject": { "type": [ "string", "null" ], "description": "The stored subject line with merge tags unreplaced; `null` for a subject-line A/B test, whose versions' subjects are in the single-message report's `variants` (the Message API returns the placeholder `{@ab_test}`); also `null` when the message has no stored subject. Otherwise the stored subject as is, so the literal `{@ab_test}` when that is the stored subject and the A/B block does not vary the subject, or no A/B block remains.", "examples": [ "Our spring season is here, {fname}", null ] }, "type": { "type": "string", "enum": [ "campaign", "automated" ], "description": "`campaign` for an email campaign (sent, or sending when `include_in_progress=1`), `automated` for an automated (nurture) message.", "examples": [ "campaign" ] }, "sent_time": { "type": [ "string", "null" ], "description": "When the message was launched; for an automated message, when it was set up or last activated. `null` when it has no launch time. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-04-15 10:00:00" ] }, "recipient_subscription": { "type": "string", "description": "The name of the subscription the message was sent to (filter by its ID with subscription_id), or `\"\"`; the Message API value.", "examples": [ "Season News" ] }, "recipient_tag": { "type": "string", "description": "The name of the tag the message was sent to (filter by its ID with tag_id), or `\"\"`; `\"\"` when sent to a subscription alone. The Message API value.", "examples": [ "" ] }, "recipient_segment": { "type": "string", "description": "The name of the segment the message was sent to (filter by its ID with segment_id), or `\"\"`; the Message API value.", "examples": [ "" ] }, "has_variants": { "type": "boolean", "description": "`true` when the message is an A/B test (still `true` when its A/B block no longer exists). Versions are never listed as rows.", "examples": [ false ] }, "sends": { "type": "integer", "description": "Distinct contacts with a send record (type 1, any sub-type). Equals the Sent row of the Sent message report.", "examples": [ 412 ] }, "delivered": { "type": "integer", "description": "Lifetime: `sends` − `bounces`; greater than or equal to the report's Delivered row. Inside an activity window: distinct contacts with a send record in the window and no bounce record for the message at any time, so never negative and never above the window's `sends` (the report's Delivered row for the same window can be negative). Will switch to confirmed delivery records (type 7 sub-type 11) once they are backfilled; the change will be announced.", "examples": [ 403 ] }, "bounces": { "type": "integer", "description": "Distinct contacts with any bounce record (type 2, sub-types 10, 11, 12, 13, 14, 15, 16), including temporary deferrals. Less than or equal to the report's Bounced row, which counts one per contact per bounce sub-type.", "examples": [ 9 ] }, "hard_bounces": { "type": "integer", "description": "Distinct contacts with a hard bounce (2/12) or an invalid address (2/16).", "examples": [ 5 ] }, "soft_bounces": { "type": "integer", "description": "Distinct contacts with an SMTP error (2/10), soft bounce (2/11), temporary deferral (2/14) or rejection (2/15). A contact can be in both hard_bounces and soft_bounces.", "examples": [ 4 ] }, "opens": { "type": "integer", "description": "Distinct contacts with any open record (type 3, any sub-type). Less than or equal to the report's Opens row, which counts one per contact per email client. Usually no larger than sends, but can be: Envoke records opens for contacts with no send record for the message.", "examples": [ 188 ] }, "clicks": { "type": "integer", "description": "Distinct contacts with any click record (type 4, any tracked link, including view-online, preferences and poll answers). Equals the report's Clicks row.", "examples": [ 57 ] }, "unsubscribes": { "type": "integer", "description": "Distinct contacts with a revoked-consent (5/11) or one-click unsubscribe (5/30) record. Between the larger of and the sum of the report's Revoked consent and One-click unsubscribe rows.", "examples": [ 4 ] }, "spam_complaints": { "type": "integer", "description": "Distinct contacts with a spam report through Envoke (5/12) or from their mailbox provider (5/13).", "examples": [ 1 ] }, "skips": { "type": "integer", "description": "Distinct contacts selected but not sent the message (type 6, any sub-type). Less than or equal to the report's Skipped row.", "examples": [ 6 ] } } }, "BounceBreakdown": { "type": "object", "description": "Distinct contacts with one bounce reason.", "required": [ "type", "label", "contacts" ], "properties": { "type": { "type": "string", "enum": [ "hard_bounce", "soft_bounce", "deferred", "rejected", "invalid_address", "other" ], "description": "Stable key: hard_bounce 2/12, soft_bounce 2/11, deferred 2/14, rejected 2/15, invalid_address 2/16, other 2/10 and the retired 2/13.", "examples": [ "hard_bounce" ] }, "label": { "type": "string", "description": "English display text; may change.", "examples": [ "Hard bounce" ] }, "contacts": { "type": "integer", "description": "Distinct contacts with this reason.", "examples": [ 3 ] } } }, "PreferenceChange": { "type": "object", "description": "Distinct contacts with one kind of preference change made from the message.", "required": [ "type", "label", "contacts" ], "properties": { "type": { "type": "string", "enum": [ "revoked_consent", "one_click_unsubscribe", "spam_reported", "subscription_changed", "language_changed", "express_consent_granted" ], "description": "Stable key: revoked_consent 5/11, one_click_unsubscribe 5/30, spam_reported 5/12 and 5/13, subscription_changed 5/17, language_changed 5/16, express_consent_granted 5/21.", "examples": [ "revoked_consent" ] }, "label": { "type": "string", "description": "English display text; may change.", "examples": [ "Revoked consent" ] }, "contacts": { "type": "integer", "description": "Distinct contacts with this change.", "examples": [ 1 ] } } }, "LinkStats": { "type": "object", "description": "One tracked link in the message. Poll answers are not listed here.", "required": [ "id", "url", "title", "type", "clicks" ], "properties": { "id": { "type": "string", "description": "The tracked link's ID.", "examples": [ "88125" ] }, "url": { "type": "string", "description": "The link as written in the message, with `utm_*` and `eid` parameters removed and merge tags unreplaced, so it can be or contain a merge tag such as `{@customfield-url_test}`; `\"\"` for the view-online and preferences links.", "examples": [ "https://example.org/tickets/pirates" ] }, "title": { "type": "string", "description": "Anchor text, or a shortened URL, cut at 60 bytes (fewer characters for non-ASCII text); a fixed title for view and pref links.", "examples": [ "Get your tickets" ] }, "type": { "type": "string", "enum": [ "link", "view", "pref" ], "description": "`link` for a content link (including links to pages with Envoke forms), `view` for view online, `pref` for the preferences and unsubscribe links.", "examples": [ "link" ] }, "clicks": { "type": "integer", "description": "Distinct contacts who clicked this link.", "examples": [ 39 ] } } }, "EmailClients": { "type": [ "object", "null" ], "description": "Open records per email client: every figure counts records (one per contact per email client), not distinct contacts, and this is the only block of the report that does. `null` for messages sent before 1 June 2022.", "required": [ "known_opens", "machine_open_records", "by_app" ], "properties": { "known_opens": { "type": "integer", "description": "Open records whose email client was recorded.", "examples": [ 214 ] }, "machine_open_records": { "type": "integer", "description": "Open records with user agent `Mozilla/5.0` (Apple Mail Privacy Protection), which Envoke classifies as machine opens. A contact has at most one per message, so this also equals the contacts with at least one machine open. There is no machine-opens metric in totals.", "examples": [ 47 ] }, "by_app": { "type": "array", "description": "Open records per email client, always five entries: Apple Mail (including machine-open records), Gmail, Outlook and Yahoo, most first (ties in that order), then Other, always last and 0 when every client was recognised.", "items": { "type": "object", "required": [ "name", "opens" ], "properties": { "name": { "type": "string", "description": "Email client.", "examples": [ "Apple Mail" ] }, "opens": { "type": "integer", "description": "Open records from this client.", "examples": [ 88 ] } } }, "examples": [ [ { "name": "Apple Mail", "opens": 88 }, { "name": "Other", "opens": 14 } ] ] } } }, "UnsubscribeReason": { "type": "object", "description": "Contacts whose current consent was revoked from this message with this reason. Current state; the whole list is `null` when an activity window is given.", "required": [ "reason", "contacts" ], "properties": { "reason": { "type": "string", "enum": [ "no_longer_interested", "never_subscribed", "too_many_emails", "irrelevant", "other" ], "description": "Stable reason key.", "examples": [ "too_many_emails" ] }, "contacts": { "type": "integer", "description": "Contacts with this reason now.", "examples": [ 1 ] } } }, "Poll": { "type": "object", "description": "One poll in the message. Counts are contacts currently holding each answer; the whole list is `null` when an activity window is given.", "required": [ "id", "name", "anonymous", "answers" ], "properties": { "id": { "type": "string", "description": "Poll ID.", "examples": [ "61" ] }, "name": { "type": "string", "description": "The poll question.", "examples": [ "Which performance will you attend?" ] }, "anonymous": { "type": "boolean", "description": "`true` for an anonymous poll; counts are still given.", "examples": [ false ] }, "answers": { "type": "array", "description": "Answers in the order the Sent message report lists them: by sort position, then alphabetically by text (poll answers are stored without a sort position, so normally alphabetical, not the order in the message).", "items": { "type": "object", "required": [ "id", "text", "contacts" ], "properties": { "id": { "type": "string", "description": "Answer ID.", "examples": [ "7301" ] }, "text": { "type": "string", "description": "Answer text.", "examples": [ "Friday 7:30 p.m." ] }, "contacts": { "type": "integer", "description": "Contacts holding this answer now.", "examples": [ 48 ] } } }, "examples": [ [ { "id": "7301", "text": "Friday 7:30 p.m.", "contacts": 48 } ] ] } } }, "Variant": { "type": "object", "description": "One version of an A/B test, counting the contacts sent that version as the report's version tabs do: the test-phase contacts and, for the winner, the contacts sent the winner after the test. The versions' sends usually add up to the message's sends; less when contacts were sent outside the versions' assignment (overrides, resends), more on old tests that recorded a contact under two versions.", "required": [ "id", "name", "test_type", "subject", "sender", "winner", "totals", "rates" ], "properties": { "id": { "type": "string", "description": "Version ID.", "examples": [ "5122" ] }, "name": { "type": "string", "description": "Version name by position: A, B, C and so on, as in the Sent message report tabs.", "examples": [ "B" ] }, "test_type": { "type": "string", "enum": [ "subject", "preheader", "sender", "content" ], "description": "What the test varies.", "examples": [ "subject" ] }, "subject": { "type": [ "string", "null" ], "description": "This version's subject for a subject test, otherwise `null`.", "examples": [ "Curtain up on Pirates, {fname}!" ] }, "sender": { "type": [ "string", "null" ], "description": "This version's sender as `Name ` for a sender test, otherwise `null`.", "examples": [ null ] }, "winner": { "type": "boolean", "description": "`true` for the winning version; `false` for every version while the test runs or when no winner was recorded.", "examples": [ true ] }, "totals": { "$ref": "#/components/schemas/Metrics" }, "rates": { "$ref": "#/components/schemas/Rates" } } }, "MessageStats": { "type": "object", "description": "The full report for one message. `totals` equal the message activity list row for the same message and window.", "required": [ "id", "name", "subject", "type", "sent_time", "has_variants", "totals", "rates", "bounces", "preference_changes", "links", "email_clients", "unsubscribe_reasons", "polls", "variants" ], "properties": { "id": { "type": "string", "description": "Envoke message ID; the Message API `id`.", "examples": [ "2001" ] }, "name": { "type": "string", "description": "The message's internal name.", "examples": [ "Spring Season Announcement" ] }, "subject": { "type": [ "string", "null" ], "description": "The stored subject line with merge tags unreplaced; `null` for a subject-line A/B test, whose versions' subjects are in the single-message report's `variants` (the Message API returns the placeholder `{@ab_test}`); also `null` when the message has no stored subject. Otherwise the stored subject as is, so the literal `{@ab_test}` when that is the stored subject and the A/B block does not vary the subject, or no A/B block remains.", "examples": [ "Our spring season is here, {fname}", null ] }, "type": { "type": "string", "enum": [ "campaign", "automated" ], "description": "`campaign` for an email campaign (sent, or sending when `include_in_progress=1`), `automated` for an automated (nurture) message.", "examples": [ "campaign" ] }, "sent_time": { "type": [ "string", "null" ], "description": "When the message was launched; for an automated message, when it was set up or last activated. `null` when it has no launch time. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-04-15 10:00:00" ] }, "has_variants": { "type": "boolean", "description": "`true` when the message is an A/B test (still `true`, with `variants` `[]`, when its A/B block no longer exists).", "examples": [ true ] }, "totals": { "$ref": "#/components/schemas/Metrics" }, "rates": { "$ref": "#/components/schemas/Rates" }, "bounces": { "type": "array", "description": "All six bounce reasons in fixed order; entries can add up to more than totals.bounces.", "items": { "$ref": "#/components/schemas/BounceBreakdown" }, "examples": [ [ { "type": "hard_bounce", "label": "Hard bounce", "contacts": 3 } ] ] }, "preference_changes": { "type": "array", "description": "All six preference changes in fixed order.", "items": { "$ref": "#/components/schemas/PreferenceChange" }, "examples": [ [ { "type": "revoked_consent", "label": "Revoked consent", "contacts": 1 } ] ] }, "links": { "type": "array", "description": "One entry per tracked link, most clicked first; entries can add up to more than totals.clicks.", "items": { "$ref": "#/components/schemas/LinkStats" }, "examples": [ [ { "id": "88125", "url": "https://example.org/tickets/pirates", "title": "Get your tickets", "type": "link", "clicks": 39 } ] ] }, "email_clients": { "$ref": "#/components/schemas/EmailClients" }, "unsubscribe_reasons": { "type": [ "array", "null" ], "description": "Reasons at least one contact chose, in the preferences page's order. Current state, so `null` when `activity_from` or `activity_to` is given.", "items": { "$ref": "#/components/schemas/UnsubscribeReason" }, "examples": [ [ { "reason": "too_many_emails", "contacts": 1 } ] ] }, "polls": { "type": [ "array", "null" ], "description": "One entry per poll; `[]` when the message has none. Current state, so `null` when `activity_from` or `activity_to` is given.", "items": { "$ref": "#/components/schemas/Poll" }, "examples": [ [] ] }, "variants": { "type": "array", "description": "One entry per A/B version, always present when `has_variants` is true (there is no parameter to request or suppress it); `[]` when the message is not an A/B test, and when its A/B block no longer exists.", "items": { "$ref": "#/components/schemas/Variant" }, "examples": [ [] ] } } }, "CompareMessage": { "type": "object", "description": "One message in a comparison.", "required": [ "id", "name", "sent_time", "totals", "rates" ], "properties": { "id": { "type": "string", "description": "Envoke message ID; the Message API `id`.", "examples": [ "2001" ] }, "name": { "type": "string", "description": "The message's internal name.", "examples": [ "Spring Season Announcement" ] }, "sent_time": { "type": [ "string", "null" ], "description": "When the message was launched; for an automated message, when it was set up or last activated. `null` when it has no launch time. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-04-15 10:00:00" ] }, "totals": { "$ref": "#/components/schemas/Metrics" }, "rates": { "$ref": "#/components/schemas/Rates" } } }, "CompareResponse": { "type": "object", "description": "Per-message totals and rates plus a combined block for the set.", "required": [ "messages", "combined" ], "properties": { "messages": { "type": "array", "description": "The messages, newest sent_time first, then highest id.", "items": { "$ref": "#/components/schemas/CompareMessage" }, "examples": [ [] ] }, "combined": { "type": "object", "description": "The set as a whole. Totals count distinct contacts across the set (a contact sent two messages counts once), so they measure reach and the rates are not averages of the messages' rates. delivered is combined sends − combined bounces for lifetime counts and, inside an activity window, the contacts who for at least one message in the set were sent it in the window and have no bounce for it. Rates are computed from the combined totals.", "required": [ "message_count", "totals", "rates" ], "properties": { "message_count": { "type": "integer", "description": "Number of messages in the set (with an activity window, after leaving out messages launched after activity_to).", "examples": [ 2 ] }, "totals": { "$ref": "#/components/schemas/Metrics" }, "rates": { "$ref": "#/components/schemas/Rates" } }, "examples": [ { "message_count": 2, "totals": { "sends": 702, "delivered": 686, "bounces": 16, "hard_bounces": 9, "soft_bounces": 7, "opens": 331, "clicks": 108, "unsubscribes": 6, "spam_complaints": 1, "skips": 9 }, "rates": { "delivered": 0.9772, "open": 0.4825, "click": 0.1574, "click_to_open": 0.3263, "bounce": 0.0228, "unsubscribe": 0.0085 } } ] } } }, "ContactActivity": { "type": "object", "description": "One contact's email activity: who, a summary across every message (inside the window when given), and a page of messages.", "required": [ "contact", "summary", "messages" ], "properties": { "contact": { "type": "object", "description": "The contact.", "required": [ "id", "email", "remote_id" ], "properties": { "id": { "type": "string", "description": "Envoke contact ID; the Contact API `id`.", "examples": [ "1004" ] }, "email": { "type": "string", "description": "Email address.", "examples": [ "maya.chen@example.org" ] }, "remote_id": { "type": "string", "description": "Remote ID, or `\"\"`.", "examples": [ "MRCT-0412" ] } }, "examples": [ { "id": "1004", "email": "maya.chen@example.org", "remote_id": "MRCT-0412" } ] }, "summary": { "type": "object", "description": "Counts of messages across every message in the report, not only the current page.", "required": [ "sends", "delivered", "bounces", "opens", "clicks", "unsubscribes", "last_send_time", "last_open_time", "last_click_time" ], "properties": { "sends": { "type": "integer", "description": "Messages the contact was sent.", "examples": [ 3 ] }, "delivered": { "type": "integer", "description": "Messages with delivered true.", "examples": [ 3 ] }, "bounces": { "type": "integer", "description": "Messages with bounced true.", "examples": [ 0 ] }, "opens": { "type": "integer", "description": "Messages with opened true.", "examples": [ 2 ] }, "clicks": { "type": "integer", "description": "Messages with clicked true.", "examples": [ 1 ] }, "unsubscribes": { "type": "integer", "description": "Messages with unsubscribed true.", "examples": [ 0 ] }, "last_send_time": { "type": [ "string", "null" ], "description": "The most recent send to the contact, or `null`. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-05-14 09:31:07" ] }, "last_open_time": { "type": [ "string", "null" ], "description": "The most recent open record (a first open of a message in an email client), or `null`. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-05-14 12:02:44" ] }, "last_click_time": { "type": [ "string", "null" ], "description": "The most recent click record (a first click on a link), or `null`. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-05-14 12:03:10" ] } }, "examples": [ { "sends": 3, "delivered": 3, "bounces": 0, "opens": 2, "clicks": 1, "unsubscribes": 0, "last_send_time": "2026-05-14 09:31:07", "last_open_time": "2026-05-14 12:02:44", "last_click_time": "2026-05-14 12:03:10" } ] }, "messages": { "type": "array", "description": "Messages the contact was sent, newest sent_time first, then highest id; paged with limit and skip.", "items": { "type": "object", "required": [ "id", "name", "sent_time", "delivered", "bounced", "opened", "first_open_time", "opens", "clicked", "clicks", "links", "unsubscribed" ], "properties": { "id": { "type": "string", "description": "Envoke message ID; the Message API `id`.", "examples": [ "2001" ] }, "name": { "type": "string", "description": "The message's internal name.", "examples": [ "Spring Season Announcement" ] }, "sent_time": { "type": "string", "description": "When this contact was sent the message (for an automated message, this contact's send). `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-05-14 09:31:07" ] }, "delivered": { "type": "boolean", "description": "Sent and no bounce record for the message. With an activity window, the send must be inside the window; a bounce counts whenever it arrived.", "examples": [ true ] }, "bounced": { "type": "boolean", "description": "Any bounce record, including a temporary deferral.", "examples": [ false ] }, "opened": { "type": "boolean", "description": "Any open record.", "examples": [ true ] }, "first_open_time": { "type": [ "string", "null" ], "description": "The contact's first open of the message, or `null`. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-05-14 12:02:44" ] }, "opens": { "type": "integer", "description": "Number of email clients the contact opened the message in.", "examples": [ 1 ] }, "clicked": { "type": "boolean", "description": "Any click record.", "examples": [ true ] }, "clicks": { "type": "integer", "description": "Number of different links clicked; the length of `links`.", "examples": [ 1 ] }, "links": { "type": "array", "description": "Links clicked, most recent first.", "items": { "type": "object", "required": [ "id", "url", "first_click_time" ], "properties": { "id": { "type": "string", "description": "Tracked link ID.", "examples": [ "88125" ] }, "url": { "type": "string", "description": "The link as written in the message, tracking parameters removed and merge tags unreplaced (it can be or contain a merge tag such as `{@customfield-url_test}`); `\"\"` for Envoke's own links (view online, preferences, poll answers).", "examples": [ "https://example.org/tickets/pirates" ] }, "first_click_time": { "type": "string", "description": "The contact's first click on this link. `YYYY-MM-DD HH:MM:SS` in the account's time zone (as the Message API), no offset.", "examples": [ "2026-05-14 12:03:10" ] } } }, "examples": [ [ { "id": "88125", "url": "https://example.org/tickets/pirates", "first_click_time": "2026-05-14 12:03:10" } ] ] }, "unsubscribed": { "type": "boolean", "description": "Revoked consent (5/11) or one-click unsubscribe (5/30) from this message.", "examples": [ false ] } } }, "examples": [ [] ] } } }, "ValidationErrorResponse": { "type": "object", "description": "HTTP 400 validation envelope. Every problem in the request is listed.", "required": [ "success", "result_data", "result_text" ], "properties": { "success": { "type": "boolean", "const": false, "description": "Always false.", "examples": [ false ] }, "result_data": { "type": "object", "description": "The errors.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "One string per problem.", "examples": [ [ "Parameter 'page' is not valid" ] ] } }, "examples": [ { "errors": [ "Parameter 'page' is not valid" ] } ] }, "result_text": { "type": "string", "const": "Validation failed, see 'result_data' -> 'errors'", "description": "Fixed text.", "examples": [ "Validation failed, see 'result_data' -> 'errors'" ] } } }, "PlainErrorResponse": { "type": "object", "description": "Plain error envelope used by 401, 404, the closed or inactive account 403, the contact activity 403, and the 400 `Invalid request` of a query timeout or database error.", "required": [ "success", "result_data", "result_text" ], "properties": { "success": { "type": "boolean", "description": "Always false.", "examples": [ false ] }, "result_data": { "type": "array", "maxItems": 0, "description": "Always empty.", "examples": [ [] ] }, "result_text": { "type": "string", "description": "The error.", "examples": [ "Invalid credentials" ] } } }, "EmptyResult": { "type": "array", "maxItems": 0, "description": "`[]`: the message or contact does not exist, belongs to another account, or is deleted (or the message has not started sending); on the message contacts report, also an event no contact has.", "examples": [ [] ] }, "MessageContactRow": { "type": "object", "description": "One contact with the requested event for the message. With fields, only the fields named.", "properties": { "id": { "type": "string", "description": "Envoke contact ID; the Contact API id.", "examples": [ "1004" ] }, "email": { "type": "string", "description": "The contact's email address now (not necessarily the address the message was sent to).", "examples": [ "maya.chen@example.org" ] }, "remote_id": { "type": "string", "description": "The contact's remote ID now, or \"\".", "examples": [ "MRCT-0412" ] }, "event_time": { "type": [ "string", "null" ], "description": "The contact's first record of the event for the message (inside the activity window when one is given), YYYY-MM-DD HH:MM:SS in the account's time zone. sent and delivered: the send; bounced: the first bounce of the reasons asked for; opened: the first open; clicked: the first click (on link_id when given); unsubscribed and spam_reported: the earlier of the two sub-types; skipped: the first skip. null for not_opened and not_clicked.", "examples": [ "2026-05-14 12:02:44" ] }, "count": { "type": "integer", "description": "opened: the number of email clients the contact opened the message in (an Apple Mail Privacy Protection open is one). clicked without link_id: the number of different links clicked. Every other event, and clicked with link_id: 1.", "examples": [ 1 ] } } } }, "responses": { "Unauthorized": { "description": "Invalid API ID or key. JSON body (sent as text/html).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlainErrorResponse" }, "example": { "success": false, "result_data": [], "result_text": "Invalid credentials" } } } }, "Forbidden": { "description": "A valid key on a closed or inactive account: `result_text` is `This account has been closed.` or `This account is not active.`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlainErrorResponse" }, "example": { "success": false, "result_data": [], "result_text": "This account has been closed." } } } }, "TooManyRequests": { "description": "The account's API limit was exceeded; `success: false` and a `result_text` naming the limit.", "content": { "application/json": { "schema": { "type": "object" } } } }, "NotFound": { "description": "A non-numeric id in the path, or an unknown path. JSON body (sent as text/html).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlainErrorResponse" }, "example": { "success": false, "result_data": [], "result_text": "404 Not Found" } } } }, "ContactForbidden": { "description": "Either the account is restricted from contact-level email activity, or a valid key is used on a closed or inactive account (`This account has been closed.` or `This account is not active.`). Both are JSON bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlainErrorResponse" }, "examples": { "restricted": { "summary": "Restricted from contact-level email activity", "value": { "success": false, "result_text": "Contact-level email activity is not available on this account", "result_data": [] } }, "closed": { "summary": "Closed account", "value": { "success": false, "result_data": [], "result_text": "This account has been closed." } } } } } } } } }