Welcome!
" } ``` --- ## Examples ### Return all templates (default pagination) ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates" ``` ### Paginate through results ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?limit=10&skip=10" ``` ### Filter by status ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?filter%5Bstatus%5D=published" ``` ### Filter by group ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?filter%5Bgroup%5D=Onboarding" ``` ### Filter by language ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?filter%5Blanguage%5D=fr" ``` ### Filter excluding a group ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?filter%5Bgroup%5D%5B%28ne%29%5D=Archived" ``` ### Sort by name ascending ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?sort%5Bname%5D=asc" ``` ### Sort by most recently created ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?sort%5Bcreate_time%5D=desc" ``` ### Return only specific fields ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?fields=id,name,status" ``` ### Return as a key-value map (for dropdowns) ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates?result_type=kvp" ``` Response: ```json { "1": "Welcome Email", "2": "Monthly Newsletter" } ``` ### Get a single template by ID ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates/42" ``` ### Get a single template with its HTML ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates/42?include_html=1" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/templates/insert/ Markdown: https://envoke-developers.pages.dev/v2/templates/insert.md # Template API - Insert Use this endpoint to create a new email template in your account. --- ## Endpoint ``` POST https://e1.envoke.com/v2/templates ``` Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON. --- ## Request Body | Field | Type | Required | Description | |---|---|---|---| | `name` | string | No | Template name. Minimum 3 characters. If omitted, auto-generated as `API Template {timestamp}`. | | `html` | string | Yes* | Full HTML content for the template. Maximum 200 KB. | | `template_id` | integer | Yes* | ID of an existing template or message to copy HTML from. | | `language` | string or integer | No | Language code (e.g. `en`, `fr`) or numeric language ID. Defaults to `en`. | | `group` | string or integer | No | Group name or group ID to assign the template to. | *Either `html` or `template_id` must be provided — but not necessarily both. If `template_id` is given, its HTML is copied into the new template. **Note:** `status` defaults to `published` if not specified on create. Pass `"unpublished"` to create the template in a draft state. --- ## Response On success, the API returns the newly created template object: ```json { "success": true, "result_text": "Created", "result_data": { "id": "42", "external_id": "a1b2c3d4e5f6", "preview_url": "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6", "name": "Welcome Email", "status": "published", "language": "en", "group": "Onboarding", "create_time": "2026-04-11 09:00:00", "modified_time": "2026-04-11 09:00:00" } } ``` `result_data.id` is the Envoke template ID. Store this if you need to update or delete the template later. The `html` field is **not** included in the create response. To retrieve the HTML, use a separate `GET /v2/templates/{id}?include_html=1` request. --- ## Validation Errors If the request body is invalid, the API returns a `400` response: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "One of the fields 'template_id' or 'html' must be provided in order to create a template" ] } } ``` Common validation errors: | Error | Cause | |---|---| | `Request body may not be empty` | No JSON body was provided. | | `One of the fields 'template_id' or 'html' must be provided in order to create a template` | Neither `html` nor `template_id` was included. | | `The field 'name' must be at least 3 characters long` | `name` was fewer than 3 characters or missing. | | `The field 'html' may not be longer than 200kB` | HTML content exceeded the 200 KB limit. | | `Invalid 'language'` | The `language` value was not a recognised language code or ID. | | `Invalid 'group'` | The `group` value did not match a valid group of type `message_template`. | | `Nothing found for 'template_id': {id}` | The `template_id` does not exist or is not accessible to your account. | | `'{field}' is not a valid field` | An unrecognised field was included in the request body. | Some errors include an `allowed_values` object: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Invalid 'language'"], "allowed_values": { "language": { "1": "English", "2": "French" } } } } ``` --- ## Examples ### Create with inline HTML ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Welcome Email", "html": "Welcome!
"}' \ "https://e1.envoke.com/v2/templates" ``` ### Create with a group and language ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Bienvenue", "html": "Bienvenue!
", "language": "fr", "group": "Onboarding"}' \ "https://e1.envoke.com/v2/templates" ``` ### Create by copying an existing template ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Welcome Email (Copy)", "template_id": 10}' \ "https://e1.envoke.com/v2/templates" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/templates/update/ Markdown: https://envoke-developers.pages.dev/v2/templates/update.md # Template API - Update Use this endpoint to update an existing template. You can update the name, status, language, group assignment, and HTML content. --- ## Endpoint ``` PATCH https://e1.envoke.com/v2/templates/{ID} ``` Replace `{ID}` with the Envoke template ID you want to update. Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON. --- ## Request Body At least one field must be provided. | Field | Type | Description | |---|---|---| | `name` | string | New name. Minimum 3 characters. | | `status` | string | `published` or `unpublished`. | | `language` | string or integer | Language code (e.g. `en`, `fr`) or numeric language ID. | | `group` | string or integer | Group name or group ID to assign. Pass an empty string (`""`) to remove the group assignment. | | `html` | string | Replacement HTML content. Maximum 200 KB. | The fields `external_id`, `preview_url`, `create_time`, and `modified_time` are silently ignored if included in the request body. If `id` is included, it must match the `{ID}` in the URL — if they differ, a validation error is returned: `"Provided 'id': {url_id} does not match 'id' in request body ({body_id})"`. --- ## Response On success, the API returns the updated template object: ```json { "success": true, "result_text": "Updated", "result_data": { "id": "42", "external_id": "a1b2c3d4e5f6", "preview_url": "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6", "name": "Updated Welcome Email", "status": "published", "language": "en", "group": "", "create_time": "2026-04-11 09:00:00", "modified_time": "2026-04-11 15:00:00" } } ``` `html` is not included in the update response body. To retrieve the updated HTML, use `GET /v2/templates/{id}?include_html=1`. --- ## Validation Errors All errors, including not-found, use the validation error envelope: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'name' must be at least 3 characters long" ] } } ``` Common errors: | Error | Cause | |---|---| | `Request body may not be empty` | No JSON body was provided. | | `The field 'name' must be at least 3 characters long` | New `name` was fewer than 3 characters. | | `The field 'html' may not be longer than 200kB` | HTML content exceeded the 200 KB limit. | | `Invalid 'status'` | `status` was not `published` or `unpublished`. | | `Invalid 'language'` | The `language` value was not recognised. | | `Invalid 'group'` | The group was not found or is not of type `message_template`. | | `Item with id '{id}' not found` | The `{ID}` in the URL does not match any template in your account. | --- ## Examples ### Rename a template ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Updated Welcome Email"}' \ "https://e1.envoke.com/v2/templates/42" ``` ### Unpublish a template ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"status": "unpublished"}' \ "https://e1.envoke.com/v2/templates/42" ``` ### Assign to a group ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"group": "Seasonal Campaigns"}' \ "https://e1.envoke.com/v2/templates/42" ``` ### Remove group assignment ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"group": ""}' \ "https://e1.envoke.com/v2/templates/42" ``` ### Replace HTML content ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"html": "New content
"}' \ "https://e1.envoke.com/v2/templates/42" ``` ### Update multiple fields at once ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Bienvenue", "language": "fr", "group": "Onboarding"}' \ "https://e1.envoke.com/v2/templates/42" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/templates/delete/ Markdown: https://envoke-developers.pages.dev/v2/templates/delete.md # Template API - Delete Use this endpoint to delete a template from your account. --- ## Endpoint ``` DELETE https://e1.envoke.com/v2/templates/{ID} ``` Replace `{ID}` with the Envoke template ID you want to delete. Authentication is via HTTP Basic Auth using your API ID and API Key. --- ## Important **Deletion is permanent from an API perspective** — a deleted template is immediately removed from all API responses and cannot be recovered via the API. Internally, templates are soft-deleted: the record is archived rather than physically removed, so the underlying data may be retained temporarily during cleanup. However, you should treat deletion as irreversible. --- ## Response On success: ```json { "success": true, "result_text": "Deleted", "result_data": [] } ``` If the template ID is not found: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Item with id '42' not found"] } } ``` --- ## Example ```bash curl -X DELETE -gs \ -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/templates/42" ``` Replace `42` with the ID of the template you want to delete, and substitute your actual API ID and API Key. --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/messages/fields/ Markdown: https://envoke-developers.pages.dev/v2/messages/fields.md # Message API - Fields Reference This article describes all fields available through the Message API. Use this as a reference when reading, creating, updating, or sending messages. --- ## Overview The Message API lets you read, create, update, delete, send, and cancel the email messages in your Envoke account. A message is one email campaign: its settings (name, sender, subject, recipients, send time) and its HTML content. Messages are created as drafts; only a `Draft` message can be changed, and sending moves it through the statuses described under [`status`](#status). The Message API answers on `/v2` only. Related resources have their own APIs: templates whose HTML a new message can copy through [`template_id`](#html-template_id-and-replace) are managed with the [Template API](https://envoke-developers.pages.dev/v2/templates/fields/), message groups (folders) with the [Group API](https://envoke-developers.pages.dev/v2/groups/fields/), the tags and subscriptions a message is sent to with the [Tag API](https://envoke-developers.pages.dev/v2/tags/fields/) and [Subscription API](https://envoke-developers.pages.dev/v2/subscriptions/fields/), and sender identities with the [Sender API](https://envoke-developers.pages.dev/v1/senders/fields/). Sending and cancelling are covered in [Sending](https://envoke-developers.pages.dev/v2/messages/sending/). The API returns no delivery, open, or click statistics; the only counts it gives are the recipient estimate in a send response. All endpoints require [HTTP Basic Auth](https://envoke-developers.pages.dev/guides/authentication/) using your API ID and API Key. --- ## Fields | Field | Type | Read-only | Required on Create | Description | |---|---|---|---|---| | `id` | string | Yes | — | Envoke message ID, assigned on creation. | | `external_id` | string | Yes | — | Externally visible identifier used in the preview URL. | | `preview_url` | string | Yes | — | Public URL to view the message in a browser. | | `create_time` | string | Yes | — | When the message was created, in the account time zone. | | `modified_time` | string | Yes | — | When the message was last changed, in the account time zone. | | `name` | string | No | No | Internal name. Generated if omitted. | | `group` | string | No | No | Name of the message group (folder), or `""`. | | `status` | string | Yes | — | Current status, e.g. `Draft` or `Sent`. Changed only by sending and cancelling. | | `send_time` | string | No | No | Scheduled send time in the account time zone, or `""`. | | `sender` | string | No | No | Sender identity as `NameSpring Season
Curtain up on {SHOW_TITLE}.
"` The complete HTML of the message, stored as sent. Envoke does not check or clean it. If it contains the `This weekFri 7:30 p.m. - The Pirates of Penzance
Sat 2:00 p.m. - Matinee
" } } ``` **Use case 3: Fill in your own HTML.** When your system already produces the HTML, send it with placeholders and the values in the same request: ```json { "html": "Dear patron, {SHOW_TITLE} opens on {OPENING_DATE}.
", "replace": { "{SHOW_TITLE}": "The Pirates of Penzance", "{OPENING_DATE}": "Friday, October 23" } } ``` Envoke merge tags such as `{@first_name}` are not protected keys. Avoid using them as `replace` keys, or the merge tag is replaced for every recipient. --- ### `sender` and `reply_to` - **Type:** String - **Read-only:** No - **Required on create:** No. `sender` defaults to the account's default sender; `reply_to` has no default. - **Accepted values (write):** An identity ID, the identity as `NameThe Pirates of Penzance
Curtain at 7:30 p.m.
" } ``` --- ## Examples ### Return the first page of messages ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages" ``` Returns the 10 most recently modified messages. Use `limit` (up to 100) and `skip` to page through the rest. ### Paginate through results ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?sort%5Bid%5D=asc&limit=100&skip=100" ``` ### Sort by name ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?sort%5Bname%5D=asc&limit=5" ``` ### Find a message by name ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5Bname%5D=Spring%20Season%20Announcement" ``` ### Filter by subject ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5Bsubject%5D=Our%20spring%20season%20is%20here" ``` ### Sent messages, by status name ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5Bstatus%5D=Sent" ``` The same filter by status code: ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5Bstatus%5D=9" ``` ### Everything except drafts ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5Bstatus%5D%5B%28ne%29%5D=Draft" ``` ### Sent or scheduled messages ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5B%28or%29%5D%5B0%5D%5Bstatus%5D=Sent&filter%5B%28or%29%5D%5B1%5D%5Bstatus%5D=Scheduled" ``` ### Messages published to the archive ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?filter%5Bpublish_archive%5D=2" ``` ### Return only specific fields ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?fields=id,name,status,send_time" ``` Response: ```json [ { "id": "2002", "name": "Auditions Open", "status": "Draft", "send_time": "" }, { "id": "2001", "name": "Spring Season Announcement", "status": "Scheduled", "send_time": "2026-10-20 09:00:00" } ] ``` With `fields` set and no `limit`, this returns up to 10,000 messages. ### Return as a key-value map ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?result_type=kvp" ``` Response: ```json { "2002": "Auditions Open", "2001": "Spring Season Announcement" } ``` ### Look up one message's ID by name ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?name=Auditions%20Open&fields=id,status&limit=1" ``` Response (an object, because `limit=1`): ```json { "id": "2002", "status": "Draft" } ``` ### Get a single message by ID ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages/2001" ``` ### Get a single message with its HTML ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages/2003?include_html=1" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/messages/insert/ Markdown: https://envoke-developers.pages.dev/v2/messages/insert.md # Message API - Insert Use this endpoint to create a new draft message in your account. To create a message and send it in one request, see [Create and send](https://envoke-developers.pages.dev/v2/messages/sending/#create-and-send). --- ## Endpoint ``` POST https://e1.envoke.com/v2/messages ``` Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be a single JSON object. --- ## Request Body | Field | Type | Required | Description | |---|---|---|---| | `html` | string | One of `html` or `template_id` | The message HTML. Max 200 kB. | | `template_id` | integer | One of `html` or `template_id` | ID of a template or message to copy the HTML from. Ignored when `html` is also sent. | | `replace` | object | No | Placeholder text to replace in the HTML before it is saved. | | `name` | string | No | Internal name. At least 3 characters. | | `group` | string | No | Name or ID of an existing message group. | | `subject` | string | No | Subject line. At least 6 characters. Required to send. | | `sender` | string | No | Identity ID, `NameAuditions Open
Auditions for our spring production start Monday.
"}' \ "https://e1.envoke.com/v2/messages" ``` The message is created as a `Draft` named `API Message 2026-10-06 10:12:05`, with the account's default sender, no subject, and no recipients. ### Create a complete message ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Spring Season Announcement", "group": "Productions", "subject": "Our spring season is here", "sender": "boxoffice@example.org", "reply_to": 413, "language": "en", "recipient_subscription": "Season News", "publish_archive": true, "utm_tag_links": true, "html": "Spring Season
Four shows, one season pass.
"}' \ "https://e1.envoke.com/v2/messages" ``` `sender` is matched by email address and `reply_to` by identity ID; both are returned as `NameDear patron, {SHOW_TITLE} opens on {OPENING_DATE}.
", "replace": {"{SHOW_TITLE}": "The Pirates of Penzance", "{OPENING_DATE}": "Friday, October 23"}}' \ "https://e1.envoke.com/v2/messages" ``` ### Send to a subscription, narrowed by a tag ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Cast Party Invitation", "subject": "You are invited to the cast party", "recipient_subscription": "Season News", "recipient_tag": "Cast Call", "html": "Join us after the final show.
"}' \ "https://e1.envoke.com/v2/messages" ``` When sent, the message goes only to contacts who have the `Cast Call` tag and are subscribed to `Season News`. ### Create a draft with a send time ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Subscriber Presale", "subject": "Presale opens Tuesday at 9", "recipient_subscription": "Season News", "send_time": "2026-10-20 09:00:00", "html": "Subscribers get first pick of seats.
"}' \ "https://e1.envoke.com/v2/messages" ``` The message is a `Draft` with `send_time` `"2026-10-20 09:00:00"` (9:00 a.m. in the account time zone). It is not scheduled until it is [sent](https://envoke-developers.pages.dev/v2/messages/sending/#send-a-draft). ### Missing content ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Spring Season Announcement"}' \ "https://e1.envoke.com/v2/messages" ``` Returns the validation error shown under [Validation Errors](#validation-errors). ### Tag and segment together ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"html": "Hello
", "recipient_tag": "Cast Call", "recipient_segment": "Lapsed Subscribers"}' \ "https://e1.envoke.com/v2/messages" ``` ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Only one of the fields 'recipient_tag' or 'recipient_segment' may be provided"] } } ``` ### Unknown group ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"html": "Hello
", "group": "Playbills"}' \ "https://e1.envoke.com/v2/messages" ``` ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Invalid 'group': 'Playbills'"], "allowed_values": { "group": { "31": "Productions", "32": "Newsletters" } } } } ``` No message is created. Create the group first with the [Group API](https://envoke-developers.pages.dev/v2/groups/fields/), or use one of the listed names or IDs. --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/messages/update/ Markdown: https://envoke-developers.pages.dev/v2/messages/update.md # Message API - Update Use this endpoint to change a draft message: its settings, its recipients, or its HTML. --- ## Endpoint ``` PATCH https://e1.envoke.com/v2/messages/{ID} ``` Replace `{ID}` with the Envoke message ID. Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be a single JSON object. There is no endpoint for updating several messages in one request. --- ## Request Body Send only the fields you want to change. Fields you leave out keep their current values, with one exception: the recipient fields are replaced as a set (see [Recipients](#recipients)). | Field | Type | Description | |---|---|---| | `name` | string | Internal name. At least 3 characters. | | `group` | string | Name or ID of an existing message group. `""` removes the group. | | `subject` | string | Subject line. At least 6 characters. | | `sender` | string | Identity ID, `Name{SHOW_TITLE}
Curtain at {CURTAIN_TIME}.
", "replace": { "{SHOW_TITLE}": "The Pirates of Penzance", "{CURTAIN_TIME}": "8:00 p.m." } } ``` `template_id` is not accepted: `The field 'template_id' is not valid for updating a message`. To switch a draft to a template's HTML, read the template with the [Template API](https://envoke-developers.pages.dev/v2/templates/read/) and send its HTML as `html`. --- ## Clearing Values | Field | To clear | Notes | |---|---|---| | `group` | `""` or `"0"` | The message has no group. | | `sender` | `""` or `"0"` | No fallback to the default sender. The message cannot be sent until a sender is set again. | | `reply_to` | `""` or `"0"` | | | `recipient_subscription`, `recipient_tag`, `recipient_segment` | `""` or `"0"` | Clearing one clears all three (see [Recipients](#recipients)). | | `recipient_language` | `""` or `"0"` | Sends to all languages. | | `language` | — | `""` or `"0"` sets `en`. | | `name`, `subject` | — | Cannot be cleared; `""` fails the minimum-length check. | | `html` | — | Cannot be cleared; `""` is ignored. | | `send_time` | — | Cannot be cleared once set (see [Dates and time zones](https://envoke-developers.pages.dev/v2/messages/fields/#dates-and-time-zones)). | Use the string `"0"`, not the number `0`: a JSON number `0` fails as an invalid value, e.g. `Invalid 'group': '0'`. --- ## ID Mismatch If the body includes `id` and it differs from `{ID}`, the request fails with a plain envelope, not the validation envelope: ```json { "success": false, "result_data": [], "result_text": "Provided 'id': 2001 does not match 'id' in request body (2002)" } ``` `"2001"` and `2001` count as the same. The same rule and message apply to `POST /v2/messages/{ID}/send` and `POST /v2/messages/{ID}/cancel`. --- ## Response On success, the API returns the updated message in full, in the same shape as a [read](https://envoke-developers.pages.dev/v2/messages/read/#response): ```json { "success": true, "result_text": "Updated", "result_data": { "id": "2002", "name": "Auditions Open", "status": "Draft", "subject": "Auditions start Monday at 7", "recipient_subscription": "", "recipient_tag": "Cast Call", "recipient_segment": "", "modified_time": "2026-10-06 11:30:17" } } ``` *(`result_data` shortened; the response contains every field.)* `result_data.id` is a string. The HTML is not included. --- ## Validation Errors ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "No message found for 'id': 2099" ] } } ``` The checks run in the order below. Each of the first six returns on its own; the field checks are then collected and returned together, before the `replace` checks. | Error | Cause | |---|---| | `Request body may not be empty` | No body, an empty body, or `{}`. | | `No message found for 'id': 2099` | No message with that ID in your account. Deleted messages and templates are not found. | | `Only 'Draft' messages can be updated, this message has the status: 'Sent'` | The message is not a draft. | | `The field 'template_id' is not valid for updating a message` | `template_id` was sent. | | `The field 'html' may not be longer than 200kB` | `html` is over 204,800 bytes. | | `Only one of the fields 'recipient_tag' or 'recipient_segment' may be provided` | Both were sent with values. | | Field errors | `'headline' is not a valid field`, the `name` and `subject` length errors, unknown lookup values with `allowed_values`, and the `send_time` errors, as listed for [create](https://envoke-developers.pages.dev/v2/messages/insert/#validation-errors). | | `The field 'html' is required for content 'replace' data` | `replace` was sent without `html`. | | `Invalid 'replace' data` | `replace` is not an object of strings with `{...}` keys, or a key targets a preference or consent link. | `Invalid JSON` and the [ID mismatch](#id-mismatch) use the plain envelope with `result_data: []`. --- ## Examples ### Change the subject and HTML ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Auditions start Monday at 7", "html": "Auditions Open
Monday at 7 p.m. in the rehearsal hall.
"}' \ "https://e1.envoke.com/v2/messages/2002" ``` ### Send to a tag instead of a subscription ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"recipient_tag": "Cast Call"}' \ "https://e1.envoke.com/v2/messages/2002" ``` If the message was going to the `Season News` subscription, it now goes to the `Cast Call` tag only. ### Clear the reply-to address ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"reply_to": ""}' \ "https://e1.envoke.com/v2/messages/2001" ``` `reply_to` is then returned as `null`. ### Set a send time ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"send_time": "2026-10-20 09:00:00"}' \ "https://e1.envoke.com/v2/messages/2002" ``` The message stays a `Draft`. The time is used when it is [sent](https://envoke-developers.pages.dev/v2/messages/sending/#send-a-draft). ### New HTML with placeholders ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"html": "{SHOW_TITLE}
Curtain at {CURTAIN_TIME}.
", "replace": {"{SHOW_TITLE}": "The Pirates of Penzance", "{CURTAIN_TIME}": "8:00 p.m."}}' \ "https://e1.envoke.com/v2/messages/2003" ``` ### Update a message that is not a draft ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Last chance for presale seats"}' \ "https://e1.envoke.com/v2/messages/2001" ``` Message `2001` is `Scheduled`, so the request fails with `Only 'Draft' messages can be updated, this message has the status: 'Scheduled'` (see [Only drafts can be updated](#only-drafts-can-be-updated)). ### Use `template_id` on update ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"template_id": 1901}' \ "https://e1.envoke.com/v2/messages/2002" ``` ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["The field 'template_id' is not valid for updating a message"] } } ``` ### Message not found ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Auditions start Monday at 7"}' \ "https://e1.envoke.com/v2/messages/2099" ``` Returns the validation error shown under [Validation Errors](#validation-errors). --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/messages/delete/ Markdown: https://envoke-developers.pages.dev/v2/messages/delete.md # Message API - Delete Use this endpoint to delete a message from your account. --- ## Endpoint ``` DELETE https://e1.envoke.com/v2/messages/{ID} ``` Replace `{ID}` with the Envoke message ID you want to delete. Authentication is via HTTP Basic Auth using your API ID and API Key. No request body is needed. --- ## Important **Deletion moves the message to the Deleted folder.** The message disappears from the API at once: a GET for it returns `[]`, and it is no longer listed. In Envoke, it appears in the **Deleted** folder of the message list, for 60 days, where it can be restored; after that Envoke's scheduled cleanup removes it permanently. Restoring is possible only in Envoke; the API has no restore endpoint. **A scheduled message is unscheduled.** Deleting a `Scheduled` message sets it back to `Draft` as well, so it is not sent. There is no need to [cancel](https://envoke-developers.pages.dev/v2/messages/sending/#cancel) it first. **Messages in most statuses can be deleted**, including `Sent` messages. These cannot: | Message | Why | |---|---| | Status `Sending` | Emails are going out. Wait until the message is `Sent`. | | Part of a nurture series | Remove it from the nurture campaign in Envoke first. | | Envoke system or offer messages | These are managed by Envoke. | --- ## Response ### Success ```json { "success": true, "result_data": [], "result_text": "Deleted" } ``` ### Message not found Returned with HTTP status `400` when the ID does not match a message in your account. This uses the plain envelope, not the validation envelope: ```json { "success": false, "result_data": [], "result_text": "Item with id '2099' not found" } ``` ### Blocked messages Returned with HTTP status `400`, in the same plain envelope, when the message cannot be deleted: | `result_text` | Cause | |---|---| | `Message: 'Spring Season Announcement' is currently sending` | The message's status is `Sending`. | | `This message cannot be deleted because it's part of the automated series: "Welcome Sequence"` | A `Nurture` message that belongs to a nurture campaign. | | `System messages cannot be deleted` or `Offer messages cannot be deleted` | A message Envoke manages. | ### Database error If the delete fails on the server, `result_text` is `Delete error: ` followed by the error detail, with HTTP status `400`. Retry the request; if it keeps failing, contact Envoke support. --- ## Example ```bash curl -X DELETE -gs \ -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages/2009" ``` Replace `2009` with the ID of the message you want to delete, and substitute your actual API ID and API Key. A `GET https://e1.envoke.com/v2/messages/2009` afterwards returns `[]`. To find the ID of a message from its name first: ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages?name=Auditions%20Open&fields=id&limit=1" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/messages/sending/ Markdown: https://envoke-developers.pages.dev/v2/messages/sending.md # Message API - Sending Use these endpoints to send a draft message, to create and send a message in one request, and to cancel a scheduled send. --- ## Endpoints | Method | URL | Description | |---|---|---| | POST | `https://e1.envoke.com/v2/messages/{ID}/send` | Send a draft message, now or at its send time. | | POST | `https://e1.envoke.com/v2/messages/send` | Create a message and send it in one request. | | POST | `https://e1.envoke.com/v2/messages/{ID}/cancel` | Cancel a scheduled message and return it to `Draft`. | Authentication is via HTTP Basic Auth using your API ID and API Key. Request bodies are JSON objects. --- ## How sending works Sending is asynchronous. A send request checks the message, estimates its recipients, and schedules it; it does not deliver any email itself. Envoke's sending process then picks up the message at its send time and moves it through these statuses: | Status | What is happening | |---|---| | `Draft` | The message can be edited. Send it with one of the endpoints above. | | `Scheduled` | The send request succeeded. The message waits for its send time. It can be [cancelled](#cancel). | | `Queuing` | The send time has passed and Envoke is selecting the recipients. | | `Sending` | The recipients are queued and the emails are going out. | | `Sent` | Every email has been handed off for delivery. | - The response to a send request is always `Message scheduled for send`, even when the message is sent straight away. - The recipient counts in the response are an **estimate** taken at the time of the request. The actual recipient list is selected again when the send starts, with the same consent and address checks, so contacts added to or removed from the tag, subscription, or segment in the meantime change who is emailed. - To follow a send, read the message with `GET /v2/messages/{ID}` and check `status`. --- ## Send a draft ``` POST https://e1.envoke.com/v2/messages/{ID}/send ``` **Request.** The body is optional. It can contain any field accepted by [update](https://envoke-developers.pages.dev/v2/messages/update/#request-body), most often `send_time`; the fields are saved to the message first, exactly as a `PATCH` would, and the message is then sent. Fields saved this way stay saved even if the send then fails. If the body includes `id`, it must match `{ID}` (see [ID Mismatch](https://envoke-developers.pages.dev/v2/messages/update/#id-mismatch)). **Requirements.** The message must be a `Draft`, and after any update in the body it must have: | Requirement | Error when missing | |---|---| | At least one recipient field | `At least one of the fields 'recipient_subscription', 'recipient_tag', or 'recipient_segment' must be set` | | A subject | `The field 'subject' must be set` | | A sender | `The field 'sender' must be set` | The three errors are returned together. `name` is not required. **Send time.** | Situation | When the message is sent | |---|---| | The body has `send_time` | At that time. It must be in the future and is read as account-local time (see [Dates and time zones](https://envoke-developers.pages.dev/v2/messages/fields/#dates-and-time-zones)). | | No `send_time` in the body, and the message has none | Immediately: on the next run of Envoke's sending process. | | No `send_time` in the body, and the message already has one | At the stored time. It is not checked again: if it has already passed, the message is sent on the next run. | A message keeps its `send_time` when it is cancelled. Sending it again with no `send_time` therefore reuses the old time, which may now be in the past and send the message at once. Send a new `send_time` when you re-send a cancelled message. A stored `send_time` cannot be cleared, so a message that has one cannot be switched back to "send now" except by sending a new, near-future time. **Response.** ```json { "success": true, "result_text": "Message scheduled for send", "result_data": { "id": "2001", "send_time": "2026-10-20 09:00:00", "recipients": { "total_selected": 412, "emails_to_be_sent": 377, "excluded_unsubscribed_contacts": 29, "excluded_invalid_emails": 2, "excluded_bounced_emails": 4, "excluded_unverified_emails": 0, "excluded_by_language": 0 } } } ``` `result_data` is not the message object: it holds the message `id` (a string, as in the URL), the `send_time` in the account time zone, and the [recipient counts](#recipient-counts). For an immediate send, `send_time` is the time of the request. **Credits.** For a prepaid account, the send is refused when the account's credit balance is lower than `emails_to_be_sent`: `Email can't be sent, the account is out of credits`. A monthly-billed account that is not yet on a paid plan, and has too few credits, gets `Email can't be sent, the account has not upgraded`. The message stays a `Draft`. **No recipients.** When `emails_to_be_sent` is `0`, the message is not scheduled and stays a `Draft`. The response is HTTP `400` with the counts, so you can see why, and no `errors` key: ```json { "success": false, "result_text": "Email can't be sent, no contacts selected", "result_data": { "id": "2004", "recipients": { "total_selected": 0, "emails_to_be_sent": 0, "excluded_unsubscribed_contacts": 0, "excluded_invalid_emails": 0, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0, "excluded_by_language": 0 } } } ``` --- ## Create and send ``` POST https://e1.envoke.com/v2/messages/send ``` **Request.** A full [create](https://envoke-developers.pages.dev/v2/messages/insert/#request-body) body (required). The message is created as a draft and then sent as described in [Send a draft](#send-a-draft), in one request. For a scheduled send, include `send_time` in the body; without it, the message is sent immediately. The body must therefore include content, a subject, and recipients; `sender` falls back to the account default. **Response.** On success, the same shape as [Send a draft](#send-a-draft), except that `result_data.id` is an **integer**: ```json { "success": true, "result_text": "Message scheduled for send", "result_data": { "id": 2005, "send_time": "2026-10-06 14:05:31", "recipients": { "total_selected": 2, "emails_to_be_sent": 2, "excluded_unsubscribed_contacts": 0, "excluded_invalid_emails": 0, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0, "excluded_by_language": 0 } } } ``` **When it fails.** If the create step fails (for example, no `html` or `template_id`), nothing is created and the create error is returned. If the create step succeeds but the send step fails (for example, no subject, or out of credits), **the draft created by the first step is kept, and its ID is not returned**; the response is the send error only. The zero-recipient response is the one exception: its `result_data.id` is the new draft's ID. Give each message a unique `name` so you can find a leftover draft with `GET /v2/messages?name=...` and fix and send it, or delete it. --- ## Recipient counts Both send endpoints return these seven counts in `result_data.recipients`. All are integers. | Key | Meaning | |---|---| | `total_selected` | Every contact in the tag, subscription, or segment (after a subscription narrows a tag or segment). | | `emails_to_be_sent` | Contacts who pass every check below. The estimated number of emails. | | `excluded_unsubscribed_contacts` | Contacts whose consent does not allow sending, such as `Not Provided`, `Revoked`, or `Expired`. On a mandatory consent message, only contacts whose consent blocks all email (such as a spam report) are counted here. | | `excluded_invalid_emails` | Contacts whose email address is not valid. | | `excluded_bounced_emails` | Contacts whose address has been marked undeliverable. | | `excluded_unverified_emails` | Contacts who have not confirmed their address. Only when your account requires email confirmation (double opt-in); otherwise `0`. | | `excluded_by_language` | Contacts whose language does not match `recipient_language`. | The counts overlap: one contact can be excluded for several reasons and is counted under each. The exclusions therefore need not add up to `total_selected` minus `emails_to_be_sent`. --- ## Cancel ``` POST https://e1.envoke.com/v2/messages/{ID}/cancel ``` **Request.** The body is optional. If it contains update fields, they are applied after the message is returned to `Draft`, as a `PATCH` would. If the body includes `id`, it must match `{ID}`. **Effect.** A `Scheduled` message goes back to `Draft` and will not be sent. It can then be updated and sent again. - **`send_time` is kept.** The cancelled draft still shows its old `send_time`. See [Send time](#send-a-draft) before sending it again. - **Only cancel scheduled messages.** The API also accepts cancel for `Queuing`, `Sending`, and `AB test in progress` messages and sets them to `Draft`, but emails already queued are still delivered. - If an update field in the body fails validation, the message has already been returned to `Draft`, but the response is the validation error. **Response.** The message in full, in the same shape as a [read](https://envoke-developers.pages.dev/v2/messages/read/#response): ```json { "success": true, "result_text": "Message reverted to draft status", "result_data": { "id": "2001", "name": "Spring Season Announcement", "status": "Draft", "send_time": "2026-10-20 09:00:00" } } ``` *(`result_data` shortened; the response contains every field.)* **Wrong status.** Cancelling a message that is not scheduled or sending fails with the status name (not quoted): ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Sending cannot be cancelled for a message with 'status': Draft"] } } ``` --- ## Errors All errors use HTTP status `400`. | Error | Endpoints | Envelope | Cause | |---|---|---|---| | `Request body may not be empty` | `/send` | Validation | No body, an empty body, or `{}`. The other two endpoints accept an empty body. | | `Invalid JSON` | All | Plain | The body is not valid JSON. | | `Invalid request` | All | Plain | The request could not be processed. | | `Provided 'id': 2001 does not match 'id' in request body (2002)` | `/{ID}/send`, `/{ID}/cancel` | Plain | The body `id` differs from the URL. | | Create errors | `/send` | Validation | Any error listed for [create](https://envoke-developers.pages.dev/v2/messages/insert/#validation-errors). Nothing is created. | | `No message found for 'id': 2099` | `/{ID}/send` | Validation | No message with that ID in your account. | | `Only 'Draft' messages can be updated, this message has the status: 'Scheduled'` | `/{ID}/send` | Validation | The message is not a draft. | | Update errors | `/{ID}/send`, `/{ID}/cancel` | Validation | Any error listed for [update](https://envoke-developers.pages.dev/v2/messages/update/#validation-errors), for fields sent in the body. | | `At least one of the fields 'recipient_subscription', 'recipient_tag', or 'recipient_segment' must be set` | `/send`, `/{ID}/send` | Validation | No recipients. | | `The field 'subject' must be set` | `/send`, `/{ID}/send` | Validation | No subject. | | `The field 'sender' must be set` | `/send`, `/{ID}/send` | Validation | No sender. | | `Email can't be sent, no contacts selected` | `/send`, `/{ID}/send` | Plain, with counts | `emails_to_be_sent` is `0`. See [No recipients](#send-a-draft). | | `Email can't be sent, the account is out of credits` | `/send`, `/{ID}/send` | Validation | Not enough prepaid credits. | | `Email can't be sent, the account has not upgraded` | `/send`, `/{ID}/send` | Validation | Monthly-billed account not yet on a paid plan. | | `Sending cannot be cancelled for a message with 'status': Draft` | `/{ID}/cancel` | Validation | The message is not scheduled or sending. | On `/send`, errors after the create step leave the new draft in place (see [Create and send](#create-and-send)). --- ## Examples ### Send a draft now ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/messages/2002/send" ``` Message `2002` has a subject, sender, and recipients and no `send_time`, so it is sent on the next run of Envoke's sending process. The response's `send_time` is the time of the request. ### Schedule a send ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"send_time": "2026-10-20 09:00:00"}' \ "https://e1.envoke.com/v2/messages/2001/send" ``` Sends at 9:00 a.m. on October 20 in the account time zone (for an account in `America/Toronto`, 9:00 a.m. Toronto time). Do not add an offset or `Z`; it would be ignored. The response is shown under [Send a draft](#send-a-draft). ### Create from a template and send ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Pirates of Penzance - Cast Notice", "template_id": 1901, "replace": {"{SHOW_TITLE}": "The Pirates of Penzance", "{CURTAIN_TIME}": "7:30 p.m."}, "subject": "Call times for opening night", "sender": "Box OfficeYou are in {BOAT_NAME}, seat {SEAT}.
"` The complete HTML of the message, stored as sent. Envoke does not check or clean it. If it contains the ``, or the email address alone. - **Example:** `"BoathouseTomorrow'\''s practice starts at 6:00 a.m. at the boathouse.
", "recipients": ["stroke.seat@example.org"]}' \ "https://e1.envoke.com/v1/send" ``` The message is named `API Message {date and time}`, filed in the `API Messages` group, and sent from the account's default sender, without open or click tracking. The response is shown under [Response](#response). ### Personalise each email with replace ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Head of the Valley - Crew Call-up", "subject": "Crew call-up: Head of the Valley", "sender": "BoathouseYou are racing in {BOAT_NAME}, seat {SEAT}.
Be at the boathouse by {CALL_TIME}.
", "recipients": [ { "email": "stroke.seat@example.org", "replace": { "{BOAT_NAME}": "Heron", "{SEAT}": "8 (stroke)", "{CALL_TIME}": "6:15 a.m." } }, { "email": "bow.seat@example.org", "replace": { "{BOAT_NAME}": "Heron", "{SEAT}": "1 (bow)", "{CALL_TIME}": "6:15 a.m." } } ] }' \ "https://e1.envoke.com/v1/send" ``` Each rower receives the HTML with their own boat, seat, and call time. The values are filled in when each email is delivered; the stored message keeps the `{BOAT_NAME}`, `{SEAT}`, and `{CALL_TIME}` placeholders. ### Fill in a template, with merge fields ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Spring Regatta Confirmation", "subject": "Your Spring Regatta entry is confirmed", "template_id": 1951, "enable_merge_fields": true, "recipients": [{"email": "stroke.seat@example.org", "replace": {"{RACE_NAME}": "Men'\''s Eight", "{START_TIME}": "9:40 a.m."}}, {"email": "bow.seat@example.org", "replace": {"{RACE_NAME}": "Mixed Four", "{START_TIME}": "11:05 a.m."}}]}' \ "https://e1.envoke.com/v1/send" ``` Copies the HTML of the `Regatta Template` (ID `1951`), which contains `Hi {@first_name}`, `{RACE_NAME}`, and `{START_TIME}`. Each recipient's `replace` values are applied first, then merge fields fill in `{@first_name}` from the contact. `"template_id": "1951"` works the same. ### Send to contacts by ID ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Erg test results are posted", "html": "Your erg test results are on the club board.
", "recipient_contact_ids": [7001, 7002, 7009]}' \ "https://e1.envoke.com/v1/send" ``` Contact `7009` does not exist: ```json { "success": true, "result_text": "Message is sending", "result_data": { "id": 3004, "new_contacts_created": 0, "summary": { "total_selected": 3, "emails_to_be_sent": 2, "excluded_unsubscribed_contacts": 0, "excluded_invalid_ids": 1, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0 }, "recipients": [ { "id": 7001, "email": "stroke.seat@example.org", "emails_to_be_sent": true }, { "id": 7002, "email": "bow.seat@example.org", "emails_to_be_sent": true }, { "excluded_invalid_ids": true } ] } } ``` ### Set every option ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Régate de printemps - Résultats", "subject": "Résultats de la régate de printemps", "group": "Crew Notices", "sender": "boathouse@example.org", "reply_to": 513, "language": "fr", "track_recipient_activity": true, "publish_archive": true, "html": "Les résultats sont en ligne : voir les résultats.
", "recipients": ["stroke.seat@example.org", "bow.seat@example.org"]}' \ "https://e1.envoke.com/v1/send" ``` Files the message in the `Crew Notices` group (ID `41`), so it also appears in the **All** folder in Envoke. The sender is found by its address (identity `512`, `BoathouseThe club'\''s water safety policy has changed. Please read it before your next outing.
", "recipients": ["stroke.seat@example.org", "bow.seat@example.org"]}' \ "https://e1.envoke.com/v1/send" ``` Contact `7001` holds the account's mandatory consent subscription; contact `7002` does not: ```json { "success": true, "result_text": "Message is sending", "result_data": { "id": 3007, "new_contacts_created": 0, "summary": { "total_selected": 2, "emails_to_be_sent": 1, "excluded_unsubscribed_contacts": 0, "excluded_invalid_emails": 0, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0, "excluded_mandatory_consent": 1 }, "recipients": [ { "id": 7001, "email": "stroke.seat@example.org", "emails_to_be_sent": true }, { "id": 7002, "email": "bow.seat@example.org", "excluded_mandatory_consent": true } ] } } ``` ### A mixed result ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Learn to Row - Week 1", "subject": "Welcome to Learn to Row", "html": "Week 1 starts Saturday at 8:00 a.m.
", "recipients": ["stroke.seat@example.org", "novice.rower@example.org", "cox@example.org", "kvrc-not-an-email"]}' \ "https://e1.envoke.com/v1/send" ``` `stroke.seat@example.org` is an existing contact with Express consent, `novice.rower@example.org` matches no contact, `cox@example.org` has unsubscribed (`Revoked`), and the last item is not an email address: ```json { "success": true, "result_text": "Message is sending", "result_data": { "id": 3006, "new_contacts_created": 1, "summary": { "total_selected": 4, "emails_to_be_sent": 2, "excluded_unsubscribed_contacts": 1, "excluded_invalid_emails": 1, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0 }, "recipients": [ { "id": 7001, "email": "stroke.seat@example.org", "emails_to_be_sent": true }, { "id": 7005, "email": "novice.rower@example.org", "new_contacts_created": true, "emails_to_be_sent": true }, { "id": 7003, "email": "cox@example.org", "excluded_unsubscribed_contacts": true }, { "email": "kvrc-not-an-email", "excluded_invalid_emails": true } ] } } ``` Two emails are sent. Contact `7005` is created for `novice.rower@example.org` and receives the account's Transactional API consent shortly after. ### Add recipients to an existing message ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"id": 3006, "recipients": ["bow.seat@example.org"]}' \ "https://e1.envoke.com/v1/send" ``` Sends message `3006`, with its content and settings unchanged, to one more contact: ```json { "success": true, "result_text": "Message is sending", "result_data": { "id": 3006, "new_contacts_created": 0, "summary": { "total_selected": 1, "emails_to_be_sent": 1, "excluded_unsubscribed_contacts": 0, "excluded_invalid_emails": 0, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0 }, "recipients": [ { "id": 7002, "email": "bow.seat@example.org", "emails_to_be_sent": true } ] } } ``` ### Errors **No content:** ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Crew call-up: Head of the Valley", "recipients": ["stroke.seat@example.org"]}' \ "https://e1.envoke.com/v1/send" ``` ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["One of the fields 'template_id' or 'html' must be provided in order to create a message"] } } ``` **No valid recipients:** ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Practice moved to 6:00 a.m.", "html": "Practice starts at 6:00 a.m.
", "recipients": ["cox@example.org", "kvrc-not-an-email"]}' \ "https://e1.envoke.com/v1/send" ``` `cox@example.org` has unsubscribed and the other item is not an address, so no message is created. The response is shown under [Partial and failed sends](#partial-and-failed-sends). **Another field with `id`:** ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"id": 3006, "subject": "Week 1 reminder", "recipients": ["bow.seat@example.org"]}' \ "https://e1.envoke.com/v1/send" ``` ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["The field 'subject' is not valid when providing an 'id'"] } } ``` Nothing is sent. Send only `id` and `recipients`. --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v1/senders/fields/ Markdown: https://envoke-developers.pages.dev/v1/senders/fields.md # Sender Identity API - Fields Reference This article describes all fields available through the Sender Identity API. Use this as a reference when reading, creating, or updating sender identities. --- ## Overview The Sender Identity API lets you manage the sender identities in your Envoke account programmatically. Sender identities are the From name and email address combinations that appear in your contacts' inboxes. Each account must have at least one sender identity, and exactly one identity is always designated as the default. All endpoints require [HTTP Basic Auth](https://envoke-developers.pages.dev/guides/authentication/) using your API ID and API Key. --- ## Fields | Field | Type | Read-only | Required on Create | Description | |---|---|---|---|---| | `id` | string | Yes | — | Unique identifier assigned on creation. | | `name` | string | No | Yes | The sender display name shown in the From field. | | `email` | string | No | Yes | The sender email address. | | `is_default` | boolean | Yes | — | Whether this is the account's default sender. | | `dkim_status` | object | — | — | DKIM verification status. Returned on create and update only. | --- ## Field Details ### `id` - **Type:** String - **Read-only:** Yes — assigned automatically on creation. - **Example:** `"42"` Used to identify the sender in update, delete, and set-default requests. --- ### `name` - **Type:** String - **Read-only:** No — updatable via PATCH. - **Required on create:** Yes - **Constraints:** Double quotes (`"`) are not allowed. - **Example:** `"City of Harborview"` The display name shown in the From field of outbound emails. Choose a name your contacts will immediately recognise. --- ### `email` - **Type:** String - **Read-only:** No — updatable via PATCH. - **Required on create:** Yes - **Constraints:** Must be a valid email address using a domain your organisation controls. Free and personal email providers are not accepted. - **Example:** `"communications@harborview.gov"` The email address shown in the From field. Use a domain your organisation owns for best deliverability results. Addresses from free or personal email providers will be rejected. --- ### `is_default` - **Type:** Boolean - **Read-only:** Yes — managed via `POST /v1/senders/{id}/default`. - **Values:** `true` or `false` - **Example:** `true` Indicates whether this sender identity is the account's current default. Exactly one identity is always the default. Use the [set default endpoint](https://envoke-developers.pages.dev/v1/senders/update/#set-the-default-sender) to change which identity is the default. The very first identity you create is automatically set as the default. --- ### `dkim_status` - **Type:** Object - **Read-only:** N/A — informational only. - **Returned by:** Create (`POST /v1/senders`) and update (`PATCH /v1/senders/{id}`) responses. **Not included** in list or single-GET responses. - **Shape:** `{ "verified": boolean, "domain": string }` | Key | Type | Description | |---|---|---| | `exists` | boolean | `true` if a DKIM private key has been generated or uploaded for this domain. | | `verified` | boolean | `true` if DKIM is configured and the DNS records have been verified. `false` if setup is incomplete. | | `domain` | string | The domain extracted from the sender's email address. | **Example:** ```json { "exists": true, "verified": true, "domain": "harborview.gov" } ``` When `verified` is `false`, DKIM has not been configured for this domain. Configuring DKIM DNS records for your domain improves email deliverability and reduces the likelihood of messages being flagged as spam. Contact Envoke support if you need assistance setting up DKIM. --- ## Error Responses **Validation errors** (missing required fields, invalid values, etc.): ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'name' is required" ] } } ``` **Not-found behaviour varies by method:** - **GET** `/senders/{id}` — when the ID is not found, returns an empty array (`[]`). - **PATCH** `/senders/{id}` and **DELETE** `/senders/{id}` — when the ID is not found, returns a validation error: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Item with id '42' not found"] } } ``` --- *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v1/senders/read/ Markdown: https://envoke-developers.pages.dev/v1/senders/read.md # Sender Identity API - Read Use the read endpoints to retrieve sender identities for your account. You can list all identities with filtering and pagination, or retrieve a single identity by ID. --- ## Endpoints | Method | URL | Description | |---|---|---| | GET | `https://e1.envoke.com/v1/senders` | Return a list of sender identities. | | GET | `https://e1.envoke.com/v1/senders/{ID}` | Return a single sender identity. | Authentication is via HTTP Basic Auth using your API ID and API Key. --- ## List Sender Identities ``` GET https://e1.envoke.com/v1/senders ``` Returns a JSON array of sender identities for your account, sorted alphabetically by name by default. Supports filtering, sorting, pagination, and field selection. ### Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `limit` | integer | `10` | Maximum number of results to return. Hard cap is `100` unless `?fields=` or `?result_type=kvp` is also set (see note below). | | `skip` | integer | `0` | Number of records to skip. Use with `limit` to paginate. | | `fields` | string | *(all)* | Comma-separated list of fields to include in each result. See limit note below. | | `result_type` | string | *(array)* | Set to `kvp` to receive results as a key-value object (`{ "id": "name" }`). See limit note below. | | `filter[id]` | string | — | Filter by sender ID. | | `filter[name]` | string | — | Filter by sender display name. | | `filter[email]` | string | — | Filter by sender email address. | | `filter[is_default]` | string | — | Filter by default status. Use `1` for the default sender, `0` for non-default senders. | | `sort[name]` | string | — | Sort by sender display name. Value: `asc` or `desc`. | | `sort[email]` | string | — | Sort by sender email address. Value: `asc` or `desc`. | **Note — limit behaviour with `?fields=` and `?result_type=kvp`:** When either of these parameters is present, the default limit increases to 10,000 (returning all records if no explicit limit is specified) and a `?limit=` value above 100 is honoured as-is. This allows full exports and dropdown population without pagination. ### Filter Operators All `filter[field]` parameters support the following operators: | Operator | Example | Description | |---|---|---| | *(none)* | `?filter[name]=City+of+Harborview` | Exact match | | `(ne)` | `?filter[name][(ne)]=City+of+Harborview` | Not equal | *Note: URL-encode brackets in production requests (e.g. `%5B` for `[`).* ### Response A JSON array of sender identity objects. Returns an empty array (`[]`) if no identities match. ```json [ { "id": "1", "name": "City of Harborview", "email": "communications@harborview.gov", "is_default": true }, { "id": "2", "name": "Parks & Recreation", "email": "parks@harborview.gov", "is_default": false } ] ``` Note: `dkim_status` is not included in list responses. It is only returned on create and update. --- ## Get a Single Sender Identity ``` GET https://e1.envoke.com/v1/senders/{ID} ``` Returns a single sender identity object. Replace `{ID}` with the Envoke sender ID. If the ID is not found, the API returns an empty array (`[]`). ### Response ```json { "id": "1", "name": "City of Harborview", "email": "communications@harborview.gov", "is_default": true } ``` --- ## Examples ### Return all sender identities (default pagination) ```bash curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/senders" ``` ### Get a single sender by ID ```bash curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/senders/1" ``` ### Filter to find the default sender ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?filter%5Bis_default%5D=1" ``` ### Filter by email address ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?filter%5Bemail%5D=communications%40harborview.gov" ``` ### Filter by name (exact match) ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?filter%5Bname%5D=Parks+%26+Recreation" ``` ### Sort by name descending ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?sort%5Bname%5D=desc" ``` ### Sort by email ascending ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?sort%5Bemail%5D=asc" ``` ### Return only specific fields ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?fields=id,name,email" ``` ### Return as a key-value map (for dropdowns) ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?result_type=kvp" ``` Response: ```json { "1": "City of Harborview", "2": "Parks & Recreation" } ``` ### Paginate through results ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "$BASE/v1/senders?limit=5&skip=5" ``` --- *Note: The curl examples above are formatted for readability. URL-encode brackets in production requests (e.g. `%5B` for `[`, `%5D` for `]`).* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v1/senders/insert/ Markdown: https://envoke-developers.pages.dev/v1/senders/insert.md # Sender Identity API - Insert Use this endpoint to create a new sender identity in your account. --- ## Endpoint ``` POST https://e1.envoke.com/v1/senders ``` Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON. --- ## Request Body | Field | Type | Required | Description | |---|---|---|---| | `name` | string | Yes | Sender display name shown in the From field. Double quotes (`"`) are not allowed. | | `email` | string | Yes | Sender email address. Must use a domain your organisation controls. | Free and personal email providers are not accepted as sender email addresses. Use a domain your organisation owns. --- ## Response On success, the API returns the newly created sender identity: ```json { "success": true, "result_text": "Created", "result_data": { "id": "1", "name": "City of Harborview", "email": "communications@harborview.gov", "is_default": true, "dkim_status": { "exists": true, "verified": true, "domain": "harborview.gov" } } } ``` `result_data.id` is the Envoke sender ID. Store this to use in update, delete, and set-default requests. `result_data.is_default` will be `true` if this is the first sender identity in your account — the first identity created is automatically set as the default. `result_data.dkim_status.verified` indicates whether DKIM is configured for this domain. If `false`, configure DKIM DNS records for your domain to improve email deliverability. --- ## Validation Errors ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'name' is required" ] } } ``` Common validation errors: | Error | Cause | |---|---| | `Request body may not be empty` | No JSON body was provided. | | `The field 'name' is required` | `name` was missing or blank. | | `Email is required` | `email` was missing or blank. | | `Email address is not valid` | The value in `email` is not a valid email address format. | | `Double quotes are not allowed in the from name field` | The `name` value contains a `"` character. | | `Double quotes are not allowed in the email field` | The `email` value contains a `"` character. | | `Third party email providers such as gmail.com, yahoo.com, etc. cannot be used as senders` | The email address uses a free or personal email provider. | | `A sender with this name and email already exists` | A sender with the same name and email combination already exists in your account. | --- ## Examples ### Create the primary sender identity ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "City of Harborview", "email": "communications@harborview.gov"}' \ "$BASE/v1/senders" ``` ### Create a department sender ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Parks & Recreation", "email": "parks@harborview.gov"}' \ "$BASE/v1/senders" ``` ### Create a second department sender ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Planning Department", "email": "planning@harborview.gov"}' \ "$BASE/v1/senders" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v1/senders/update/ Markdown: https://envoke-developers.pages.dev/v1/senders/update.md # Sender Identity API - Update Use these endpoints to update an existing sender identity or change the account's default sender. --- ## Endpoints | Method | URL | Description | |---|---|---| | PATCH | `https://e1.envoke.com/v1/senders/{ID}` | Update the name and/or email of a sender identity. | | POST | `https://e1.envoke.com/v1/senders/{ID}/default` | Set a sender identity as the account's default. | Authentication is via HTTP Basic Auth using your API ID and API Key. --- ## Update a Sender Identity ``` PATCH https://e1.envoke.com/v1/senders/{ID} ``` Replace `{ID}` with the Envoke sender ID you want to update. The request body must be JSON. ### Request Body At least one field must be provided. | Field | Type | Description | |---|---|---| | `name` | string | Updated sender display name. Double quotes (`"`) are not allowed. | | `email` | string | Updated sender email address. Must use a domain your organisation controls. | `id` and `is_default` are read-only and cannot be updated via PATCH. To change the default sender, use `POST /v1/senders/{ID}/default` (see below). If `id` is included in the request body, it must match the `{ID}` in the URL. If they differ, a validation error is returned: `"Provided 'id': {url_id} does not match 'id' in request body ({body_id})"`. ### Response On success, the API returns the updated sender identity including `dkim_status`: ```json { "success": true, "result_text": "Updated", "result_data": { "id": "2", "name": "Parks & Recreation", "email": "parks@harborview.gov", "is_default": false, "dkim_status": { "verified": true, "domain": "harborview.gov" } } } ``` `dkim_status.verified` reflects the DKIM state for the sender's domain after the update. If you changed the `email` field to use a different domain, this indicates whether the new domain has DKIM configured. ### Validation Errors Common errors: | Error | Cause | |---|---| | `Request body may not be empty` | No JSON body was provided. | | `Item with id '42' not found` | The `{ID}` in the URL does not match any sender in your account. | | `Provided 'id': {url_id} does not match 'id' in request body ({body_id})` | `id` in the request body differs from `{ID}` in the URL. | | `The field 'name' is required` | `name` was provided but is blank or whitespace only. | | `Email is required` | `email` was provided but is blank. | | `Email address is not valid` | The value in `email` is not a valid email format. | | `Double quotes are not allowed in the from name field` | The `name` value contains a `"` character. | | `Double quotes are not allowed in the email field` | The `email` value contains a `"` character. | | `Third party email providers such as gmail.com, yahoo.com, etc. cannot be used as senders` | The email address uses a free or personal provider. | | `A sender with this name and email already exists` | Another sender in your account already has this name and email combination. | ### Examples **Update the name only:** ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Office of Communications"}' \ "$BASE/v1/senders/1" ``` **Update the email only:** ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "info@harborview.gov"}' \ "$BASE/v1/senders/1" ``` **Update both name and email:** ```bash curl -X PATCH -gs \ -u "$API_ID:$API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Office of Communications", "email": "info@harborview.gov"}' \ "$BASE/v1/senders/1" ``` --- ## Set the Default Sender ``` POST https://e1.envoke.com/v1/senders/{ID}/default ``` Promotes the specified sender identity to be the account's default. Replace `{ID}` with the sender ID to promote. The default sender is used automatically when no sender is explicitly specified in a campaign. Exactly one identity is always the default — when you promote a new identity, the previous default is automatically demoted. This endpoint requires no request body. ### Response On success: ```json { "success": true, "result_text": "Updated", "result_data": [] } ``` If the sender ID is not found: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Item with id '42' not found"] } } ``` ### Example **Set a department sender as the default:** ```bash curl -X POST -gs \ -u "$API_ID:$API_KEY" \ "$BASE/v1/senders/2/default" ``` **To confirm the change, read back the updated sender:** ```bash curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/senders/2" ``` Expected: `is_default` is `true`. --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v1/senders/delete/ Markdown: https://envoke-developers.pages.dev/v1/senders/delete.md # Sender Identity API - Delete Use this endpoint to delete a sender identity from your account. --- ## Endpoint ``` DELETE https://e1.envoke.com/v1/senders/{ID} ``` Replace `{ID}` with the Envoke sender ID you want to delete. Authentication is via HTTP Basic Auth using your API ID and API Key. --- ## Important **Deletion is permanent.** Deleted sender identities cannot be recovered via the API. **The default sender cannot be deleted.** If you need to remove the current default, first use `POST /v1/senders/{ID}/default` to promote a different identity as the default, then delete the former default. --- ## Response On success: ```json { "success": true, "result_text": "Deleted", "result_data": [] } ``` If the sender ID is not found: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["Item with id '42' not found"] } } ``` If you attempt to delete the default sender: ```json { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": ["The default sender identity cannot be deleted"] } } ``` --- ## Examples ### Delete a sender identity ```bash curl -X DELETE -gs \ -u "$API_ID:$API_KEY" \ "$BASE/v1/senders/4" ``` ### Promote a new default, then delete the old one If you need to delete the current default, promote another sender first: ```bash # Step 1 — promote sender 2 as the new default curl -X POST -gs \ -u "$API_ID:$API_KEY" \ "$BASE/v1/senders/2/default" # Step 2 — delete the old default (sender 1) curl -X DELETE -gs \ -u "$API_ID:$API_KEY" \ "$BASE/v1/senders/1" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/reports/fields/ Markdown: https://envoke-developers.pages.dev/v2/reports/fields.md # 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. --- ## Overview 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`: | Group | Endpoints | Article | |---|---|---| | Message activity | `GET https://e1.envoke.com/v2/reports/messages` | [Message Activity](https://envoke-developers.pages.dev/v2/reports/messages/) | | Message stats | `GET https://e1.envoke.com/v2/reports/messages/{id}` and `GET https://e1.envoke.com/v2/reports/messages/compare` | [Message Stats](https://envoke-developers.pages.dev/v2/reports/message-stats/) | | Message contacts | `GET https://e1.envoke.com/v2/reports/messages/{id}/contacts` | [Message Contacts](https://envoke-developers.pages.dev/v2/reports/message-contacts/) | | Contact activity | `GET https://e1.envoke.com/v2/reports/contacts/{id}` and `GET https://e1.envoke.com/v2/reports/contacts` | [Contact Activity](https://envoke-developers.pages.dev/v2/reports/contacts/) | Every message report uses the same ten [metrics](#fields), 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](https://envoke-developers.pages.dev/v2/messages/fields/), message folders (`group_id`) are managed with the [Group API](https://envoke-developers.pages.dev/v2/groups/fields/), and the tags and subscriptions used as filters with the [Tag API](https://envoke-developers.pages.dev/v2/tags/fields/) and [Subscription API](https://envoke-developers.pages.dev/v2/subscriptions/fields/). Contact `id` values are the same as the `id` of the [Contact API](https://envoke-developers.pages.dev/v1/contacts/fields/). 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](https://envoke-developers.pages.dev/guides/authentication/) using your API ID and API Key. --- ## Fields The ten metrics, in the order they appear in every response. Each is an integer count of **distinct contacts**. | Field | Type | Read-only | Required on Create | Description | |---|---|---|---|---| | `sends` | integer | Yes | — | Contacts the message was sent to. | | `delivered` | integer | Yes | — | `sends` minus `bounces`; inside an activity window, contacts sent the message in the window who have no bounce for it. Never negative. | | `bounces` | integer | Yes | — | Contacts with any bounce. | | `hard_bounces` | integer | Yes | — | Contacts with a hard bounce or an invalid address. | | `soft_bounces` | integer | Yes | — | Contacts with a soft bounce, deferral, rejection, or SMTP error. | | `opens` | integer | Yes | — | Contacts who opened the message. | | `clicks` | integer | Yes | — | Contacts who clicked any tracked link. | | `unsubscribes` | integer | Yes | — | Contacts who revoked consent or used one-click unsubscribe from the message. | | `spam_complaints` | integer | Yes | — | Contacts who reported the message as spam. | | `skips` | integer | Yes | — | Contacts selected for the message but not sent it. | The rates, returned only by the single-message and compare reports, are decimals rounded to four places: | Field | Type | Read-only | Required on Create | Description | |---|---|---|---|---| | `delivered` | number or null | Yes | — | `delivered` ÷ `sends`. | | `open` | number or null | Yes | — | `opens` ÷ `delivered`. | | `click` | number or null | Yes | — | `clicks` ÷ `delivered`. | | `click_to_open` | number or null | Yes | — | `clicks` ÷ `opens`. | | `bounce` | number or null | Yes | — | `bounces` ÷ `sends`. | | `unsubscribe` | number or null | Yes | — | `unsubscribes` ÷ `sends`. | --- ## Field Details ### How the counts work 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](#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`](#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. --- ### `sends` - **Type:** Integer - **Codes:** Type `1` (Sent), any sub-type. Today every send record has sub-type `11` (send attempted). - **Counts:** Distinct contacts. - **Sent message report:** Equal to the Sent row, `.stats[] | select(.type=="Sent") | .data`. - **Example:** `412` 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`](#skips), not here. --- ### `delivered` - **Type:** Integer - **Codes:** Computed. Lifetime (no activity window): [`sends`](#sends) − [`bounces`](#bounces). With an activity window: contacts with a send record (type `1`) inside the window and no bounce record (type `2`) for the message, whenever that bounce was recorded. - **Counts:** Distinct contacts. Never negative. - **Sent message report:** Lifetime: greater than or equal to the Delivered row, `.stats[] | select(.type=="Delivered") | .data`. The report subtracts its Bounced row (one per contact per bounce sub-type), so the two are equal only when no contact bounced in two ways. With an activity window there is no fixed relation: the report subtracts the window's Bounced row from the window's Sent row and can show a negative Delivered. - **Example:** `403` 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. --- ### `bounces` - **Type:** Integer - **Codes:** Type `2`, any sub-type: `10` SMTP error, `11` soft bounce, `12` hard bounce, `13` skipped for fail score (no longer written), `14` temporarily deferred, `15` rejected, `16` invalid email address. A few messages sent before 2015 carry bounce records with a retired sub-type outside this list: they count here, but in neither `hard_bounces` nor `soft_bounces` and in no entry of the single-message report's `bounces`. - **Counts:** Distinct contacts. - **Sent message report:** Less than or equal to the Bounced row, `.stats[] | select(.type=="Bounced") | .data`, which counts one per contact per bounce sub-type. Equal when no contact bounced in two ways. - **Example:** `9` Includes temporary deferrals (`14`), so a contact deferred and then delivered counts as bounced. --- ### `hard_bounces` - **Type:** Integer - **Codes:** Type `2`, sub-types `12` (hard bounce) and `16` (invalid email address). - **Counts:** Distinct contacts. - **Sent message report:** Between the larger of, and the sum of, the Hard bounce and Invalid email address rows (`.stats[] | select(.type=="Hard bounce")`, `select(.type=="Invalid email address")`). There is no single report row. - **Example:** `5` --- ### `soft_bounces` - **Type:** Integer - **Codes:** Type `2`, sub-types `10` (SMTP error), `11` (soft bounce), `14` (temporarily deferred), and `15` (rejected). - **Counts:** Distinct contacts. - **Sent message report:** No matching row. The report shows sub-types `11` (Soft bounce) and `10` (Other) as rows; `14` and `15` are inside its Bounced row only. - **Example:** `4` 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` - **Type:** Integer - **Codes:** Type `3`, any sub-type. The sub-type identifies the email client (user agent) the open came from; sub-type `1` is an open with no user agent and `11` an open recorded before user agents were tracked. - **Counts:** Distinct contacts. - **Sent message report:** Less than or equal to the Opens row, `.stats[] | select(.type=="Opens") | .data`, which counts one per contact per email client. Equal when no contact opened in two email clients. The report's Opens row can therefore be larger than its Sent row. `opens` is usually no larger than `sends`, but it can be: Envoke records opens and clicks for contacts with no send record for the message (see [Did not open and did not click](https://envoke-developers.pages.dev/v2/reports/message-contacts/#did-not-open-and-did-not-click)), and those contacts count in `opens` and `clicks` but not in `sends`. - **Example:** `188` 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`](https://envoke-developers.pages.dev/v2/reports/message-stats/#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` - **Type:** Integer - **Codes:** Type `4`, any sub-type. The sub-type is the tracked link, including the view-online link, the preferences and unsubscribe links, form links, and poll answers. - **Counts:** Distinct contacts. - **Sent message report:** Equal to the Clicks row, `.stats[] | select(.type=="Clicks") | .data`. - **Example:** `57` 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. --- ### `unsubscribes` - **Type:** Integer - **Codes:** Type `5`, sub-types `11` (revoked consent) and `30` (one-click unsubscribe). - **Counts:** Distinct contacts. - **Sent message report:** Between the larger of, and the sum of, the Revoked consent row (`.stats[] | select(.type=="Revoked consent") | .data`, the `5/11` part) and the One-click unsubscribe row (`select(.type=="One-click unsubscribe")`, the `5/30` part). A contact in both rows counts once here. - **Example:** `4` 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. --- ### `spam_complaints` - **Type:** Integer - **Codes:** Type `5`, sub-types `12` (reported through Envoke's report-abuse link) and `13` (reported to the recipient's mailbox provider and passed back to Envoke). - **Counts:** Distinct contacts. - **Sent message report:** Between the larger of, and the sum of, the Envoke spam reported and External spam reported rows. - **Example:** `1` --- ### `skips` - **Type:** Integer - **Codes:** Type `6`, any sub-type: `11` API error, `12` invalid email address, `13` no consent to send email, `14` invalid parameters, `15` unverified email address. - **Counts:** Distinct contacts. - **Sent message report:** Less than or equal to the Skipped row, `.stats[] | select(.type=="Skipped") | .data`, which counts one per contact per skip reason. The report has no Skipped row for messages sent before 17 June 2014, when skips began to be recorded. - **Example:** `6` Contacts who were in the message's recipient list when it was sent but were not sent it. They are not in `sends`. --- ### Rates Rates appear in the `rates` object of the [single-message and compare reports](https://envoke-developers.pages.dev/v2/reports/message-stats/), 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`](#delivered): | Rate | Formula | Denominator | |---|---|---| | `delivered` | `delivered` ÷ `sends` | Contacts sent | | `open` | `opens` ÷ `delivered` | Contacts delivered | | `click` | `clicks` ÷ `delivered` | Contacts delivered | | `click_to_open` | `clicks` ÷ `opens` | Contacts who opened | | `bounce` | `bounces` ÷ `sends` | Contacts sent | | `unsubscribe` | `unsubscribes` ÷ `sends` | Contacts sent | 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`](#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`](#clicks)). --- ### Messages Rows of the message activity list and the header of the single-message report describe the message with these fields: | Field | Type | Description | |---|---|---| | `id` | string | Envoke message ID; the Message API `id`. | | `name` | string | The message's internal name. | | `subject` | string or null | The stored subject line, merge tags unreplaced. `null` for a subject-line A/B test, whose versions have different subjects: `has_variants` is `true` and each version's subject is in the `variants` of the [single-message report](https://envoke-developers.pages.dev/v2/reports/message-stats/#ab-tests). (The Message API returns the stored placeholder `{@ab_test}` for the same message.) An A/B test of the preheader, sender, or content has one subject and returns it. The stored subject is returned as is, so the Reports API also returns the literal placeholder `{@ab_test}` when that is the stored subject and the message's A/B block does not vary the subject (a preheader, sender, or content test), or no A/B block remains. Also `null`, with `has_variants` `false`, when the message has no stored subject (old messages without a content row), as the Message API returns it. | | `type` | string | `campaign` for an email campaign, `automated` for an automated (nurture) message. | | `sent_time` | string or null | When the message was launched, `YYYY-MM-DD HH:MM:SS` in your account's time zone. For an automated message, the time it was set up or last activated, not the time of any one send. `null` when the message has no launch time. | | `has_variants` | boolean | `true` when the message is an A/B test. It stays `true` when the message's A/B block no longer exists; the single-message report's `variants` is then `[]`. | `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](https://envoke-developers.pages.dev/v2/reports/message-contacts/) (`event=opened` for `opens`, and so on). --- ### Times and time zone 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](https://envoke-developers.pages.dev/v2/messages/fields/#dates-and-time-zones) 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. 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. --- ## Shared Query Parameters ### Date parameters Two pairs of optional parameters, used by different endpoints: | Parameter | Bounds | Used by | |---|---|---| | `sent_from`, `sent_to` | The message's `sent_time`: which messages are listed. | Message activity list | | `activity_from`, `activity_to` | The time of each activity record: which records are counted. | Every endpoint | - Both pairs are optional and can be combined. With no `sent_*` parameter, messages sent at any time are listed; with no `activity_*` parameter, every count is lifetime. - Each takes `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space as `%20`). A date alone means the whole day: a `_from` date starts at `00:00:00` and a `_to` date ends at `23:59:59`. Both bounds are inclusive. - Values are read in your account's time zone (see [Times and time zone](#times-and-time-zone)), the zone the Message API uses. - The year must be from 1970 to 2999. Any other value, including a valid date in another format (`10/24/2026`, `2026-10-24T09:00:00Z`, `yesterday`), an impossible date (`2026-02-30`), or a year outside that range (`0000-01-01`, `9999-12-31`), returns HTTP 400: `Invalid 'sent_from': '10/24/2026' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`, with the parameter's own name. - A `_from` later than its `_to` is not an error; nothing matches. 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. ### `limit` and `skip` Lists (the message activity list, the message contacts report, and the `messages` array of the contact report) page with `limit` and `skip`: | Parameter | Type | Default | Description | |---|---|---|---| | `limit` | integer | `10` | Maximum number of items. Values above `100` return 100. `limit=0`, a limit of zeros such as `00`, or an empty `limit` gives the default. `limit=1` returns an array of one item, not a bare object. | | `skip` | integer | `0` | Number of items to 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](https://envoke-developers.pages.dev/v2/reports/message-contacts/#fields-and-the-10000-limit)). ### Unknown parameters 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`. --- ## Error Responses **Validation errors** return HTTP **400** with the validation envelope. Every problem in the request is listed: ```json { "success": false, "result_data": { "errors": [ "Invalid 'sent_from': '10/24/2026' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)", "Parameter 'page' is not valid" ] }, "result_text": "Validation failed, see 'result_data' -> 'errors'" } ``` The validation strings shared by every endpoint: | Error | Cause | |---|---| | `Parameter 'page' is not valid` | A parameter the endpoint does not accept. | | `Invalid 'sent_from': '10/24/2026' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)` | A date parameter (`sent_from`, `sent_to`, `activity_from`, `activity_to`) in another format, not a real date, or with a year outside 1970 to 2999. | | `Invalid 'limit': 'ten'` | `limit` is not a whole number. | | `Invalid 'skip': 'abc'` | `skip` is not a whole number. | | `Parameter 'limit' accepts one value` | A single-value parameter sent as an array (`limit[]=5`, `type[]=campaign`, `sent_from[]=2026-01-01`): `limit`, `skip`, `type`, `include_in_progress`, the four dates, `tag_id`, `segment_id`, `subscription_id`, `group_id` on compare, and `event`, `link_id`, `fields`, `email` and `remote_id`. Only `message_id` (on the list and compare), `group_id` (on the list only) and `bounce_type` (on the message contacts report) accept arrays. | 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: ```json { "success": false, "result_data": [], "result_text": "Invalid request" } ``` 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: ```json { "success": false, "result_data": [], "result_text": "404 Not Found" } ``` 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](https://envoke-developers.pages.dev/v2/reports/contacts/#errors). The message contacts report returns the same `403` for every event; see [Message Contacts errors](https://envoke-developers.pages.dev/v2/reports/message-contacts/#errors). ### Not found **Not-found behaviour varies by endpoint:** - **GET** `/reports/messages` — a filter that matches nothing returns `[]` with HTTP 200. A `message_id` that does not exist, belongs to another account, or is deleted is simply absent. - **GET** `/reports/messages/{id}` — a message that does not exist, belongs to another account, is deleted, or has not started sending returns `[]` with HTTP 200. - **GET** `/reports/messages/compare` — any `message_id` that is not a sent or automated message in your account returns HTTP 400 listing each one: `No message found for 'message_id': 2099`. An unknown `group_id` returns `No message group found for 'group_id': 39`. - **GET** `/reports/messages/{id}/contacts` — a message that does not exist, belongs to another account, is deleted, or has not started sending returns `[]` with HTTP 200, as does an event no contact has. - **GET** `/reports/contacts/{id}` — a contact that does not exist, belongs to another account, or is deleted returns `[]` with HTTP 200. - **GET** `/reports/contacts` — an `email` or `remote_id` that matches no contact returns `[]` with HTTP 200. --- *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/reports/messages/ Markdown: https://envoke-developers.pages.dev/v2/reports/messages.md # 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. --- ## Endpoints | Method | URL | Description | |---|---|---| | GET | `https://e1.envoke.com/v2/reports/messages` | Return activity metrics per message. | Authentication is via HTTP Basic Auth using your API ID and API Key. --- ## List Message Activity ``` GET https://e1.envoke.com/v2/reports/messages ``` Returns a JSON array of rows, one per message, most recently sent first. Each row describes the message and gives its ten [metrics](https://envoke-developers.pages.dev/v2/reports/fields/#fields) as integers. When nothing matches, the response is `[]`. The list has no rates and no breakdowns; for those, request the message's [single report](https://envoke-developers.pages.dev/v2/reports/message-stats/). ### Which messages are included By default the list includes: - sent email campaigns (Message API status `Sent`), and - automated messages (status `Nurture`). `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](https://envoke-developers.pages.dev/v2/reports/message-stats/#ab-tests). ### Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `message_id` | integer or array | — | One message ID (`message_id=2001`) or several (`message_id[]=2001&message_id[]=2004`). | | `group_id` | integer or array | — | One message folder ID or several. Messages filed in the folder or in any of its subfolders, at any depth, are included, as in the folder report in Envoke. | | `tag_id` | integer | — | Only messages sent to this tag. One value. | | `segment_id` | integer | — | Only messages sent to this segment. One value. | | `subscription_id` | integer | — | Only messages sent to this subscription. One value. The account's mandatory subscription is not returned by the Subscription API, so messages sent to it are selected by `message_id`, `group_id` or date unless you know its ID from the app. | | `type` | string | *(both)* | `campaign` or `automated`. | | `include_in_progress` | integer | `0` | `1` to include campaigns still sending. | | `sent_from` | string | — | Only messages whose `sent_time` is on or after this date or time. See [Date parameters](https://envoke-developers.pages.dev/v2/reports/fields/#date-parameters). | | `sent_to` | string | — | Only messages whose `sent_time` is on or before this date or time. | | `activity_from` | string | — | Count only activity on or after this date or time. | | `activity_to` | string | — | Count only activity on or before this date or time. | | `limit` | integer | `10` | Maximum number of rows; values above `100` return 100. | | `skip` | integer | `0` | Number of rows to skip. | The filters combine with AND. Any other parameter returns HTTP 400 (`Parameter 'segment' is not valid`); see [Unknown parameters](https://envoke-developers.pages.dev/v2/reports/fields/#unknown-parameters). ### Recipient list filters `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: | Filter | Matches a message whose | |---|---| | `subscription_id=514` | `recipient_subscription` is that subscription, with or without a tag or segment narrowing it. | | `tag_id=512` | `recipient_tag` is that tag, alone or narrowed by a subscription. | | `segment_id=77` | `recipient_segment` is that segment. | 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](https://envoke-developers.pages.dev/v2/tags/read/)) and `GET https://e1.envoke.com/v2/subscriptions` ([Subscription API](https://envoke-developers.pages.dev/v2/subscriptions/read/)); 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. ### Date window `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: | Request | Result | |---|---| | no date parameter | Every message, lifetime counts. | | `sent_from=2026-04-01&sent_to=2026-04-30` | Messages launched in April, lifetime counts. | | `activity_from=2026-05-01&activity_to=2026-05-31` | Every matching message launched by the end of May, counting only May's activity. A message launched in April appears with `sends` `0` and its May opens and clicks. | | `sent_from=2026-04-01&sent_to=2026-04-30&activity_from=2026-05-01&activity_to=2026-05-31` | Messages launched in April, counting only their May activity. | 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`](https://envoke-developers.pages.dev/v2/reports/fields/#delivered). ### Ordering and pagination 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. ### Response fields | Field | Type | Description | |---|---|---| | `id` | string | Message ID; the Message API `id`. | | `name` | string | Internal name. | | `subject` | string or null | Stored subject line; `null` for a subject-line A/B test, and for a message with no stored subject (then `has_variants` is `false`). Can be the placeholder `{@ab_test}` (see [Messages](https://envoke-developers.pages.dev/v2/reports/fields/#messages)). | | `type` | string | `campaign` or `automated`. | | `sent_time` | string or null | Launch time, `YYYY-MM-DD HH:MM:SS`, account time zone. | | `recipient_subscription` | string | The name of the subscription the message was sent to, or `""`. The same value the Message API returns. Filter by the subscription's ID with `subscription_id`. | | `recipient_tag` | string | The name of the tag the message was sent to, or `""`. `""` when the message was sent to a subscription alone. Filter by the tag's ID with `tag_id`. | | `recipient_segment` | string | The name of the segment the message was sent to, or `""`. Filter by the segment's ID with `segment_id`. | | `has_variants` | boolean | `true` for an A/B test. | | `sends` … `skips` | integer | The ten [metrics](https://envoke-developers.pages.dev/v2/reports/fields/#fields), in glossary order. | See [Messages](https://envoke-developers.pages.dev/v2/reports/fields/#messages) in the fields reference for `subject`, `type`, and `sent_time` in detail. ### Response ```json [ { "id": "2004", "name": "Pirates Opening Night", "subject": null, "type": "campaign", "sent_time": "2026-05-14 09:30:00", "recipient_subscription": "Season News", "recipient_tag": "", "recipient_segment": "", "has_variants": true, "sends": 386, "delivered": 379, "bounces": 7, "hard_bounces": 4, "soft_bounces": 3, "opens": 201, "clicks": 64, "unsubscribes": 2, "spam_complaints": 0, "skips": 3 }, { "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 }, { "id": "2002", "name": "Auditions Open", "subject": "Auditions for The Pirates of Penzance", "type": "campaign", "sent_time": "2026-03-10 18:00:00", "recipient_subscription": "", "recipient_tag": "Cast Call", "recipient_segment": "", "has_variants": false, "sends": 64, "delivered": 62, "bounces": 2, "hard_bounces": 1, "soft_bounces": 1, "opens": 47, "clicks": 21, "unsubscribes": 0, "spam_complaints": 0, "skips": 1 } ] ``` --- ## Errors Invalid parameters return HTTP 400 with the validation envelope (see [Error Responses](https://envoke-developers.pages.dev/v2/reports/fields/#error-responses)). Besides the shared date, `limit`, `skip`, and unknown-parameter errors, the list returns: | Error | Cause | |---|---| | `Invalid 'message_id': 'abc'` | A `message_id` value that is not a whole number. The same form for `group_id`, `tag_id`, `segment_id`, and `subscription_id`. | | `Parameter 'tag_id' accepts one value` | A single-value parameter sent as an array (`tag_id[]=512`, `limit[]=5`, `type[]=campaign`): every parameter except `message_id` and `group_id`. | | `Invalid 'type': 'nurture' (possible values: 'campaign', 'automated')` | `type` is not `campaign` or `automated`. | | `Invalid 'include_in_progress': 'yes' (possible values: '0', '1')` | `include_in_progress` is not `0` or `1`. | 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 `[]`. --- ## Examples ### The ten most recent messages ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages" ``` ### Second page of 25 ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?limit=25&skip=25" ``` ### Lifetime counts for two messages ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?message_id%5B%5D=2001&message_id%5B%5D=2004" ``` The rows come back newest first, not in the order the IDs were given. ### Messages launched in April ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?sent_from=2026-04-01&sent_to=2026-04-30&limit=100" ``` ### May activity for one message ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?message_id=2001&activity_from=2026-05-01&activity_to=2026-05-31" ``` 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): ```json [ { "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": 0, "delivered": 0, "bounces": 0, "hard_bounces": 0, "soft_bounces": 0, "opens": 12, "clicks": 3, "unsubscribes": 1, "spam_complaints": 0, "skips": 0 } ] ``` ### Automated messages only ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?type=automated" ``` Response: ```json [ { "id": "2006", "name": "Welcome to Maple Ridge", "subject": "Welcome to Maple Ridge Community Theatre, {fname}", "type": "automated", "sent_time": "2025-09-02 08:00:00", "recipient_subscription": "", "recipient_tag": "", "recipient_segment": "", "has_variants": false, "sends": 1284, "delivered": 1261, "bounces": 23, "hard_bounces": 15, "soft_bounces": 8, "opens": 702, "clicks": 233, "unsubscribes": 11, "spam_complaints": 2, "skips": 40 } ] ``` ### Messages in one folder ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?group_id=31" ``` The rows include the messages filed in the folder's subfolders. ### Messages sent to one tag ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?tag_id=512" ``` ### Messages launched in December 2021 ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?sent_from=2021-12-01&sent_to=2021-12-31" ``` 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): ```json [ { "id": "2003", "name": "Holiday Gala Invitation", "subject": "You're invited to the Holiday Gala", "type": "campaign", "sent_time": "2021-12-01 10:00:00", "recipient_subscription": "Season News", "recipient_tag": "", "recipient_segment": "", "has_variants": false, "sends": 355, "delivered": 349, "bounces": 6, "hard_bounces": 4, "soft_bounces": 2, "opens": 171, "clicks": 38, "unsubscribes": 3, "spam_complaints": 0, "skips": 12 } ] ``` ### Including campaigns still sending ```bash curl -X GET -gs -u "$API_ID:$API_KEY" \ "https://e1.envoke.com/v2/reports/messages?type=campaign&include_in_progress=1" ``` --- *Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.* *Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).* --- URL: https://envoke-developers.pages.dev/v2/reports/message-stats/ Markdown: https://envoke-developers.pages.dev/v2/reports/message-stats.md # Reports API - Message Stats Use the message stats reports to retrieve the full report for one message (totals, rates, bounce and preference breakdowns, links, email clients, unsubscribe reasons, polls, and A/B variants), or to compare several messages or a whole folder side by side with a combined total. --- ## Endpoints | Method | URL | Description | |---|---|---| | GET | `https://e1.envoke.com/v2/reports/messages/{ID}` | Return the full report for one message. | | GET | `https://e1.envoke.com/v2/reports/messages/compare` | Return totals and rates for several messages, or for every message in a folder, plus a combined block. | Authentication is via HTTP Basic Auth using your API ID and API Key. --- ## Get a Single Message Report ``` GET https://e1.envoke.com/v2/reports/messages/{ID} ``` Returns one JSON object: the message, its ten [metrics](https://envoke-developers.pages.dev/v2/reports/fields/#fields) in `totals`, its six [rates](https://envoke-developers.pages.dev/v2/reports/fields/#rates) in `rates`, and the breakdowns below. Replace `{ID}` with the Envoke message ID. The `totals` are the same numbers the [message activity list](https://envoke-developers.pages.dev/v2/reports/messages/) returns for the message with the same activity window. To list the contacts behind a total, a bounce reason, or a link, use the [message contacts report](https://envoke-developers.pages.dev/v2/reports/message-contacts/). The report is available for sent campaigns, automated messages, and campaigns that have started sending. A message that does not exist, belongs to another account, is deleted, or has not started sending (a draft or a scheduled message) returns `[]` with HTTP 200. ### Query Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `activity_from` | string | — | Count only activity on or after this date or time. See [Date parameters](https://envoke-developers.pages.dev/v2/reports/fields/#date-parameters). | | `activity_to` | string | — | Count only activity on or before this date or time. | Every count in the report, including the breakdowns, `links`, and `email_clients`, uses the window. `unsubscribe_reasons` and `polls` describe contacts as they are now and cannot be limited to a window, so when `activity_from` or `activity_to` is given both are `null` (see below). Any other parameter, including `sent_from` and `sent_to`, returns HTTP 400 (`Parameter 'sent_from' is not valid`). ### Response fields | Field | Type | Description | |---|---|---| | `id`, `name`, `subject`, `type`, `sent_time`, `has_variants` | | As in the [message activity list](https://envoke-developers.pages.dev/v2/reports/messages/#response-fields). | | `totals` | object | The ten metrics. | | `rates` | object | The six rates. | | `bounces` | array | Contacts per bounce reason. | | `preference_changes` | array | Contacts per preference change. | | `links` | array | Contacts per tracked link. | | `email_clients` | object or null | Open records (not contacts) per email client. `null` for messages sent before June 2022. | | `unsubscribe_reasons` | array or null | Contacts per reason given when unsubscribing. `null` when an activity window is given. | | `polls` | array or null | Answers to each poll in the message; `[]` when the message has none. `null` when an activity window is given. | | `variants` | array | One object per A/B version, always present when `has_variants` is `true`; `[]` when the message is not an A/B test, and when its A/B block no longer exists. | ### `bounces` One entry per bounce reason, always all six, in this order. `contacts` is the number of distinct contacts with that reason: | `type` | `label` | Codes | |---|---|---| | `hard_bounce` | `Hard bounce` | `2/12` | | `soft_bounce` | `Soft bounce` | `2/11` | | `deferred` | `Temporarily deferred` | `2/14` | | `rejected` | `Rejected` | `2/15` | | `invalid_address` | `Invalid email address` | `2/16` | | `other` | `Other` | `2/10` (SMTP error) and the retired `2/13` | A contact with two bounce reasons is in two entries, so the entries can add up to more than `totals.bounces`. On a few messages sent before 2015, bounce records with a retired sub-type count in `totals.bounces` but appear in no entry, and no `bounce_type` of the [message contacts report](https://envoke-developers.pages.dev/v2/reports/message-contacts/) selects them. `hard_bounces` covers `hard_bounce` and `invalid_address`; `soft_bounces` covers `soft_bounce`, `deferred`, `rejected`, and the SMTP-error part of `other`. The `type` values are stable keys; `label` is English display text and may change. The contacts behind an entry: [message contacts](https://envoke-developers.pages.dev/v2/reports/message-contacts/) with `event=bounced&bounce_type={type}`. ### `preference_changes` One entry per kind of preference change made from the message, always all six, in this order: | `type` | `label` | Codes | |---|---|---| | `revoked_consent` | `Revoked consent` | `5/11` | | `one_click_unsubscribe` | `One-click unsubscribe` | `5/30` | | `spam_reported` | `Spam reported` | `5/12` and `5/13` | | `subscription_changed` | `Subscription changed` | `5/17` | | `language_changed` | `Language changed` | `5/16` | | `express_consent_granted` | `Express consent granted` | `5/21` | `totals.unsubscribes` is the distinct contacts across `revoked_consent` and `one_click_unsubscribe`; `totals.spam_complaints` equals `spam_reported`. Each entry equals the Sent message report row with the same label, except `spam_reported`, which combines two report rows. A one-click unsubscribe on a message sent with a primary subscription removes the contact from that subscription but records only `one_click_unsubscribe`, not `subscription_changed`. Nurture campaign changes (`5/18`) are not reported. The contacts behind `revoked_consent` and `one_click_unsubscribe` together: [message contacts](https://envoke-developers.pages.dev/v2/reports/message-contacts/) with `event=unsubscribed`; behind `spam_reported`: `event=spam_reported`. The other three entries have no contact list. ### `links` One entry per tracked link in the message with at least one click (inside the window, when one is given), most clicked first; a link nobody clicked has no entry: | Field | Type | Description | |---|---|---| | `id` | string | The tracked link's ID. | | `url` | string | The link as written in the message, with Envoke's tracking parameters (`utm_*`, `eid`) removed; `""` for the view-online and preferences links. Merge tags are not replaced, so `url` can be or contain a merge tag (`{@customfield-url_test}`) rather than a valid URL. | | `title` | string | The link's anchor text, or a shortened URL when it has none, cut at 60 bytes (fewer characters when the text has accented or other non-ASCII characters); the view-online and preferences links have a fixed title. | | `type` | string | `link` for a link in the content, including links to pages with Envoke forms; `view` for the view-online link; `pref` for the preferences and unsubscribe links. | | `clicks` | integer | Distinct contacts who clicked this link. | A contact who clicked two links is in both entries, so the entries can add up to more than `totals.clicks`. Poll answers are tracked as clicks and counted in `totals.clicks`, but are reported under `polls`, not here. When the same URL appears twice in a message, each copy has its own entry; the Sent message report merges them into one row whose count is the sum of the entries. The contacts behind an entry: [message contacts](https://envoke-developers.pages.dev/v2/reports/message-contacts/) with `event=clicked&link_id={id}`. ### `email_clients` The email client panel of the Sent message report, from the open records' user agents. Every figure in this block counts **open records**, one per contact per email client, not distinct contacts, so `known_opens` can be larger than `totals.opens`. It is the only part of the report that counts records rather than contacts. | Field | Type | Description | |---|---|---| | `known_opens` | integer | Open records whose email client was recorded. | | `machine_open_records` | integer | Open records made by Apple Mail Privacy Protection (user agent `Mozilla/5.0`), which Envoke classifies as machine opens. A contact has at most one such record per message, so this also equals the number of contacts with at least one machine open, including contacts who also opened in another email client. There is no machine-opens figure in `totals`. | | `by_app` | array | `{ "name", "opens" }` per email client, always five entries: `Apple Mail` (including the machine-open records), `Gmail`, `Outlook`, and `Yahoo`, most opens first (ties in that order), then `Other` for every client Envoke does not recognise, always last and `0` when every client was recognised. | `email_clients` is `null` for a message sent before 1 June 2022, when Envoke began recording user agents. Opens recorded with no user agent are in neither `known_opens` nor `by_app`, so `known_opens` can be smaller than the report's Opens row. ### `unsubscribe_reasons` One entry per reason, in the order the preferences page lists them, for reasons at least one contact chose: | Field | Type | Description | |---|---|---| | `reason` | string | `no_longer_interested`, `never_subscribed`, `too_many_emails`, `irrelevant`, or `other`. | | `contacts` | integer | Contacts whose current consent was revoked from this message with this reason. | This counts contacts **as they are now**: a contact who unsubscribed from this message and later gave consent again is no longer counted. Because it describes the present rather than activity at a time, `unsubscribe_reasons` is `null` when `activity_from` or `activity_to` is given. Giving a reason is optional, so the entries usually add up to less than `totals.unsubscribes`. ### `polls` One entry per poll in the message; `[]` when it has none, and `null` when an activity window is given. | Field | Type | Description | |---|---|---| | `id` | string | The poll's ID. | | `name` | string | The poll question. | | `anonymous` | boolean | `true` for an anonymous poll. The counts are still given; the contacts are not identifiable in Envoke. | | `answers` | array | `{ "id", "text", "contacts" }` per answer, in the order the Sent message report lists them: by the answer's sort position, then alphabetically by text. Envoke stores poll answers without a sort position, so this is normally alphabetical, not the order of the answers in the message. `contacts` is the number of contacts who currently hold that answer. | Poll answers are stored on the contact, so the counts describe contacts **as they are now**, not activity: every contact in the account who holds the answer today is counted, however they came to hold it. For that reason `polls` is `null` when `activity_from` or `activity_to` is given. ### A/B tests For an A/B test, `has_variants` is `true`, the message's `subject` is `null` for a subject-line test, `totals` and `rates` cover every version together (including the contacts sent the winning version after the test), and `variants` has one object per version, each with its own subject or sender. `variants` is always included when `has_variants` is `true`; there is no parameter to request it or leave it out. It is `[]` when the message's A/B block no longer exists, although `has_variants` is still `true`. For a test that does not vary the subject (preheader, sender, or content), `subject` is the stored subject, which can be the literal placeholder `{@ab_test}` (see [Messages](https://envoke-developers.pages.dev/v2/reports/fields/#messages)). | Field | Type | Description | |---|---|---| | `id` | string | The version's ID. | | `name` | string | `A`, `B`, `C`, ... in the order of the versions, as in the Sent message report's tabs. | | `test_type` | string | What the test varies: `subject`, `preheader`, `sender`, or `content`. | | `subject` | string or null | This version's subject line, for a subject test; otherwise `null`. | | `sender` | string or null | This version's sender as `Name
|
