# Envoke Developers

> Reference documentation for Envoke's REST APIs: contacts and consent, tags and subscriptions, templates, messages, reporting, and webhooks. All requests go to https://e1.envoke.com with the API version in the path (/v1 or /v2) and use HTTP Basic Auth with your API ID and API Key. Every page is also available as plain Markdown at its URL with .md appended, and the merged OpenAPI 3.1 description of every published endpoint is at /openapi.json.

## Getting started

- [Authentication](https://envoke-developers.pages.dev/guides/authentication.md): Every request to the Envoke REST APIs is authenticated with HTTP Basic Auth: your API ID is the username and your API Key is the password. This article explains where to find them, what must be in place before they work, how API limits apply, and what the API returns when it refuses a request.
- [Which API do I use?](https://envoke-developers.pages.dev/guides/which-api.md): Envoke's REST API is a set of small APIs, one per resource. This article explains which APIs answer on /v1 and which on /v2, how tags, subscriptions, and mandatory consent relate to each other, when to send with the Send API or the Message API, how the Reports API relates to the reports in Envoke, and what your account needs before its first send.
- [Your first integration](https://envoke-developers.pages.dev/guides/first-integration.md): This walkthrough builds a small integration end to end with curl: it defines a custom field and a tag, creates or updates a contact that uses them, creates a template from HTML, subscribes a webhook to the result, sends the template to the contact, and receives the webhook. The examples use a fictional organisation, the Birchwood Community Garden, which assigns garden plots to its members. Each step links to the full reference for the endpoint it uses.

## Contacts and audience

- [Contact API - Fields Reference](https://envoke-developers.pages.dev/v1/contacts/fields.md): This article describes all fields available through the Contact API. Use this as a reference when reading, creating, or updating contacts.
- [Contact API - Read](https://envoke-developers.pages.dev/v1/contacts/read.md): Use the read endpoints to retrieve contacts from your account. You can list contacts with filtering, sorting, and pagination, or retrieve a single contact by ID.
- [Contact API - Insert](https://envoke-developers.pages.dev/v1/contacts/insert.md): Use this endpoint to create a new contact in your account, or, with upsert, to create the contact or update it if it already exists.
- [Contact API - Update](https://envoke-developers.pages.dev/v1/contacts/update.md): Use these endpoints to update existing contacts. You can update one contact by its ID, one contact found by email or another key field, or several contacts in one request.
- [Contact API - Delete](https://envoke-developers.pages.dev/v1/contacts/delete.md): Use this endpoint to delete a contact from your account.
- [Tag API - Fields Reference](https://envoke-developers.pages.dev/v2/tags/fields.md): This article describes all fields available through the Tag API. Use this as a reference when reading, creating, or updating tags.
- [Tag API - Read](https://envoke-developers.pages.dev/v2/tags/read.md): Use the read endpoints to retrieve tags for your account. You can list all tags with filtering and sorting, or retrieve a single tag by ID.
- [Tag API - Insert](https://envoke-developers.pages.dev/v2/tags/insert.md): Use this endpoint to create a new tag in your account.
- [Tag API - Update](https://envoke-developers.pages.dev/v2/tags/update.md): Use this endpoint to update an existing tag. You can update the name, group assignment, description, and display names.
- [Tag API - Delete](https://envoke-developers.pages.dev/v2/tags/delete.md): Use this endpoint to delete a tag from your account.
- [Tag API - Add and Remove Contacts](https://envoke-developers.pages.dev/v2/tags/contacts.md): Use these endpoints to assign contacts to a tag or remove them in bulk. Both operations are idempotent — adding a contact that is already tagged, or removing one that is not tagged, produces no error.
- [Subscription API - Fields Reference](https://envoke-developers.pages.dev/v2/subscriptions/fields.md): This article describes all fields available through the Subscription API. Use this as a reference when reading, creating, or updating subscriptions.
- [Subscription API - Read](https://envoke-developers.pages.dev/v2/subscriptions/read.md): Use the read endpoints to retrieve subscriptions for your account. You can list all subscriptions with filtering and sorting, or retrieve a single subscription by ID.
- [Subscription API - Insert](https://envoke-developers.pages.dev/v2/subscriptions/insert.md): Use this endpoint to create a new subscription in your account.
- [Subscription API - Update](https://envoke-developers.pages.dev/v2/subscriptions/update.md): Use this endpoint to update an existing subscription. You can update the name, group assignment, preference page access, display names, and display descriptions.
- [Subscription API - Delete](https://envoke-developers.pages.dev/v2/subscriptions/delete.md): Use this endpoint to delete a subscription from your account.
- [Subscription API - Add and Remove Contacts](https://envoke-developers.pages.dev/v2/subscriptions/contacts.md): Use these endpoints to subscribe contacts to a subscription or unsubscribe them in bulk. Both operations are idempotent — adding a contact that is already subscribed, or removing one that is not subscribed, produces no error.
- [Custom Field API - Fields Reference](https://envoke-developers.pages.dev/v2/customfields/fields.md): This article describes all fields available through the Custom Field API. Use this as a reference when reading, creating, or updating custom fields.
- [Custom Field API - Read](https://envoke-developers.pages.dev/v2/customfields/read.md): Use the read endpoints to retrieve custom field definitions for your account. You can retrieve all fields at once or look up a single field by its ID.
- [Custom Field API - Insert](https://envoke-developers.pages.dev/v2/customfields/insert.md): Use this endpoint to create a new contact-scoped custom field for your account.
- [Custom Field API - Update](https://envoke-developers.pages.dev/v2/customfields/update.md): Use this endpoint to update an existing custom field. You can update a field's name and/or description. The field_type cannot be changed after creation.
- [Custom Field API - Delete](https://envoke-developers.pages.dev/v2/customfields/delete.md): Use this endpoint to permanently delete a custom field from your account.
- [Group API - Fields Reference](https://envoke-developers.pages.dev/v2/groups/fields.md): This article describes all fields available through the Group API. Use this as a reference when reading, creating, or updating groups.
- [Group API - Read](https://envoke-developers.pages.dev/v2/groups/read.md): Use the read endpoints to retrieve groups for your account. You can list all groups for a given item type with filtering and sorting, or retrieve a single group by ID.
- [Group API - Insert](https://envoke-developers.pages.dev/v2/groups/insert.md): Use this endpoint to create a new group in your account.
- [Group API - Update](https://envoke-developers.pages.dev/v2/groups/update.md): Use this endpoint to update an existing group. You can rename the group or change its parent.
- [Group API - Delete](https://envoke-developers.pages.dev/v2/groups/delete.md): Use this endpoint to delete a group from your account.

## Content and sending

- [Template API - Fields Reference](https://envoke-developers.pages.dev/v2/templates/fields.md): This article describes all fields available through the Template API. Use this as a reference when reading, creating, or updating templates.
- [Template API - Read](https://envoke-developers.pages.dev/v2/templates/read.md): Use the read endpoints to retrieve email templates for your account. You can list all templates with filtering and sorting, retrieve a single template by ID, or fetch a template's full HTML content.
- [Template API - Insert](https://envoke-developers.pages.dev/v2/templates/insert.md): Use this endpoint to create a new email template in your account.
- [Template API - Update](https://envoke-developers.pages.dev/v2/templates/update.md): Use this endpoint to update an existing template. You can update the name, status, language, group assignment, and HTML content.
- [Template API - Delete](https://envoke-developers.pages.dev/v2/templates/delete.md): Use this endpoint to delete a template from your account.
- [Message API - Fields Reference](https://envoke-developers.pages.dev/v2/messages/fields.md): This article describes all fields available through the Message API. Use this as a reference when reading, creating, updating, or sending messages.
- [Message API - Read](https://envoke-developers.pages.dev/v2/messages/read.md): Use the read endpoints to retrieve messages from your account. You can list messages with filtering, sorting, and pagination, or retrieve a single message by ID, optionally with its HTML.
- [Message API - Insert](https://envoke-developers.pages.dev/v2/messages/insert.md): 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.
- [Message API - Update](https://envoke-developers.pages.dev/v2/messages/update.md): Use this endpoint to change a draft message: its settings, its recipients, or its HTML.
- [Message API - Delete](https://envoke-developers.pages.dev/v2/messages/delete.md): Use this endpoint to delete a message from your account.
- [Message API - Sending](https://envoke-developers.pages.dev/v2/messages/sending.md): Use these endpoints to send a draft message, to create and send a message in one request, and to cancel a scheduled send.
- [Send API - Fields Reference](https://envoke-developers.pages.dev/v1/send/fields.md): This article describes all fields accepted by the Send API. Use this as a reference when sending a message to a list of recipients.
- [Send API - Send](https://envoke-developers.pages.dev/v1/send/send.md): Use this endpoint to create a message and send it immediately to a list of recipients, or to send an earlier Send API message to more recipients.
- [Sender Identity API - Fields Reference](https://envoke-developers.pages.dev/v1/senders/fields.md): This article describes all fields available through the Sender Identity API. Use this as a reference when reading, creating, or updating sender identities.
- [Sender Identity API - Read](https://envoke-developers.pages.dev/v1/senders/read.md): 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.
- [Sender Identity API - Insert](https://envoke-developers.pages.dev/v1/senders/insert.md): Use this endpoint to create a new sender identity in your account.
- [Sender Identity API - Update](https://envoke-developers.pages.dev/v1/senders/update.md): Use these endpoints to update an existing sender identity or change the account's default sender.
- [Sender Identity API - Delete](https://envoke-developers.pages.dev/v1/senders/delete.md): Use this endpoint to delete a sender identity from your account.

## Reporting

- [Reports API - Fields Reference](https://envoke-developers.pages.dev/v2/reports/fields.md): 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.
- [Reports API - Message Activity](https://envoke-developers.pages.dev/v2/reports/messages.md): 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.
- [Reports API - Message Stats](https://envoke-developers.pages.dev/v2/reports/message-stats.md): 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.
- [Reports API - Message Contacts](https://envoke-developers.pages.dev/v2/reports/message-contacts.md): Use the message contacts report to list the contacts behind a number in a message's report: who was sent the message, who opened it, who clicked a particular link, who bounced, who did not open it. It is the API form of clicking a count in the Sent message report in Envoke.
- [Reports API - Contact Activity](https://envoke-developers.pages.dev/v2/reports/contacts.md): Use the contact activity report to retrieve one contact's email history: which messages they were sent and what they did with each one (delivered, bounced, opened, clicked which links, unsubscribed), with a summary across all of them.

## Webhooks

- [Hooks API — Fields Reference](https://envoke-developers.pages.dev/v1/hooks/fields.md): This article describes all fields available through the Hooks API. Use it as a reference when creating, reading, or deleting webhook subscriptions.
- [Hooks API — Read](https://envoke-developers.pages.dev/v1/hooks/read.md): Use the read endpoints to retrieve webhook subscriptions for your account. You can list all subscriptions or retrieve a single one by ID.
- [Hooks API — Create](https://envoke-developers.pages.dev/v1/hooks/insert.md): Use this endpoint to create a new webhook subscription in your account.
- [Hooks API — Delete](https://envoke-developers.pages.dev/v1/hooks/delete.md): Use this endpoint to permanently remove a webhook subscription from your account.
- [Hooks API — Webhook Payloads](https://envoke-developers.pages.dev/v1/hooks/payloads.md): This article describes the payload Envoke delivers to your endpoint for each event type.

## Email HTML

- [Writing Your Own Email HTML](https://envoke-developers.pages.dev/email-html/overview.md): These pages are for developers and designers who write email HTML themselves and bring it into Envoke through the Templates, Messages, or Send API, or paste it into the Edit HTML page. They explain what the HTML needs so that it can be edited in Envoke's drag-and-drop editor, and what Envoke does to it between your code and the inbox.
- [Getting HTML into Envoke](https://envoke-developers.pages.dev/email-html/getting-html-into-envoke.md): Your HTML reaches Envoke through one of the three APIs or the Edit HTML page in the drag-and-drop editor. None of them checks or cleans the HTML; this page lists what each one does accept, limit, and change.
- [Making HTML Editable](https://envoke-developers.pages.dev/email-html/editable-templates.md): The drag-and-drop editor does not parse arbitrary HTML into blocks. It works on a small, fixed structure of sections, rows, and editable regions, marked with class names. This page shows the minimum structure the editor needs, ending with a complete template you can paste in and adapt.
- [Block Reference](https://envoke-developers.pages.dev/email-html/blocks.md): Markup for each kind of block the drag-and-drop editor can edit. Each example is one row: put it inside a section as shown in Making HTML Editable. The examples use the 660-pixel width of a one-column section; in a column, use the column's width instead (see Columns).
- [Styles, Fonts, and Mobile](https://envoke-developers.pages.dev/email-html/css-and-mobile.md): How to style HTML for the drag-and-drop editor: inline styles, the one style block Envoke keeps, fonts, the classes that control the phone layout, and what to expect from Outlook and dark mode.
- [Merge Tags and Conditionals](https://envoke-developers.pages.dev/email-html/merge-tags.md): Merge tags are placeholders that Envoke fills in for each contact when an email is sent. This page lists the tags you can use in your own HTML, how their values are written into the email, and what happens when a tag is misspelled or has no value.
- [Unsubscribe Link, Address, and Footer](https://envoke-developers.pages.dev/email-html/unsubscribe-and-footer.md): Anti-spam laws such as Canada's CASL and the US CAN-SPAM Act require commercial email to give recipients a way to unsubscribe and to include the sender's postal address. You can place both in your own footer, or leave them out and let Envoke add its default footer. This page explains how Envoke decides, and what it does and does not check.
- [What Happens When Envoke Sends](https://envoke-developers.pages.dev/email-html/what-happens-at-send.md): The HTML stored in Envoke is not exactly the HTML your recipients receive. When each email is sent, Envoke personalises it, adds tracking and, if needed, a footer, and generates a plain-text version. This page lists every change, in order, so you can tell which differences in a received email come from Envoke.
- [Accessibility and Testing](https://envoke-developers.pages.dev/email-html/testing-and-accessibility.md): What Envoke handles for accessibility and what is left to you, followed by the checks to run before a template or message is used for a real send.

## Machine-readable

- [llms-full.txt](https://envoke-developers.pages.dev/llms-full.txt): every page above in one file
- [openapi.json](https://envoke-developers.pages.dev/openapi.json): merged OpenAPI 3.1 description of every published endpoint
- [Contacts OpenAPI](https://envoke-developers.pages.dev/v1/contacts/openapi.json): the Contacts API on its own
- [Tags OpenAPI](https://envoke-developers.pages.dev/v2/tags/openapi.json): the Tags API on its own
- [Subscriptions OpenAPI](https://envoke-developers.pages.dev/v2/subscriptions/openapi.json): the Subscriptions API on its own
- [Custom fields OpenAPI](https://envoke-developers.pages.dev/v2/customfields/openapi.json): the Custom fields API on its own
- [Groups OpenAPI](https://envoke-developers.pages.dev/v2/groups/openapi.json): the Groups API on its own
- [Templates OpenAPI](https://envoke-developers.pages.dev/v2/templates/openapi.json): the Templates API on its own
- [Messages OpenAPI](https://envoke-developers.pages.dev/v2/messages/openapi.json): the Messages API on its own
- [Send API OpenAPI](https://envoke-developers.pages.dev/v1/send/openapi.json): the Send API API on its own
- [Senders OpenAPI](https://envoke-developers.pages.dev/v1/senders/openapi.json): the Senders API on its own
- [Reports OpenAPI](https://envoke-developers.pages.dev/v2/reports/openapi.json): the Reports API on its own
- [Hooks OpenAPI](https://envoke-developers.pages.dev/v1/hooks/openapi.json): the Hooks API on its own