Which API do I use?

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.

---

The APIs and Their Versions

Every API is on the same host, https://e1.envoke.com, and uses the same API ID and API Key (see Authentication). Each API answers on one version only, so the version is part of the API’s address rather than a choice:

API	Path	What it does
Contacts	/v1/contacts	Read, create, upsert, update, and delete contacts, including their consent, custom field values, tags, and subscriptions.
Send API	/v1/send	Send one message immediately to up to 1,000 listed recipients per request.
Senders	/v1/senders	Manage sender identities, the From name and address of your messages.
Hooks	/v1/hooks.json	Manage webhook subscriptions.
Tags	/v2/tags	Manage tags, and add or remove contacts in bulk.
Subscriptions	/v2/subscriptions	Manage subscriptions, and add or remove contacts in bulk.
Custom fields	/v2/customfields	Define custom fields. Values are written to contacts through the Contact API.
Groups	/v2/groups/tags, /v2/groups/subscriptions, /v2/groups/messages, /v2/groups/templates	Manage the groups (folders) that organise tags, subscriptions, messages, and templates.
Templates	/v2/templates	Manage email templates.
Messages	/v2/messages	Create, schedule, send, and cancel messages to a tag, subscription, or segment, and read or delete messages.
Reports	/v2/reports/messages, /v2/reports/contacts	Read the email activity counts of messages and contacts.

The conventions differ from one API to another rather than by version:

• IDs. Most APIs return IDs as strings, such as "42". The Send API’s response and the Message API’s create-and-send response return the message id as an integer, as does the PATCH /v1/contacts/{id} response for the contact id. Webhook subscription IDs are 32-character hexadecimal strings.
• Errors. Every API uses the validation envelope Validation failed, see 'result_data' -> 'errors' for most errors, but the empty-body error and the response for an ID that is not found differ between APIs. Each is listed under Error Responses at the end of the API’s fields reference, for example Contact API errors.
• Hooks. The Hooks API’s documented paths end in .json, and creating a subscription returns HTTP 201 with a body of {"id": "..."} instead of the success envelope (see Hooks API - Create).

The Contact API’s error for an unknown tag or subscription name suggests the endpoint /interests. That endpoint is not part of this reference; list names with the Tag and Subscription APIs instead.

---

Tags, Subscriptions, and Mandatory Consent

A contact can hold three kinds of list membership. They are separate resources in Envoke but share one field on the Contact API.

Kind	What it is for	Seen by contacts	Managed with
Tag	Segmenting contacts by topic, preference, or area of interest. Also called an interest: tag groups have the type interest.	Where tags are displayed publicly, such as website subscription forms, under their display_names.	Tag API
Subscription	A type of communication contacts opt in to or out of, such as a weekly newsletter.	On your public preference page, unless its prefpage_access is "private".	Subscription API
Mandatory consent subscription	Your account’s one subscription for mandatory (consent-exempt) messages. Only contacts who hold it are sent a mandatory message.	Its description is given in each mandatory message as the reason it was sent.	Not returned by the Subscription API. Contacts are given it through the Contact API’s interests, or when a mandatory Send API request creates them.

On the Contact API, the single field interests holds the names of all three kinds; there are no separate tags or subscriptions fields.

How Each API Identifies Them

The Contact API writes a contact’s tags, subscriptions, and mandatory consent through one field, so it identifies each item by its name. The Tag and Subscription APIs each manage one kind of item and identify it by its id in the URL. Both refer to the same items: a tag’s name from the Tag API is what goes in interests, and its id is the numeric ID the Contact API accepts as an object key.

API	How an item is identified
Contact API, create and update	By name in interests. Matching ignores case and treats a space and an underscore as the same. In the object form ({ "Volunteer": "Set" }), a key can also be the item’s numeric ID.
Contact API, read filters	filter[interests] takes the exact name, case-sensitive. IDs are not accepted (see Filterable and sortable fields).
Tag and Subscription APIs	By id in the URL, for example POST https://e1.envoke.com/v2/tags/{ID}/contacts, which adds up to 1,000 contacts by contact_ids or contact_emails in one request (Tag API - Add and Remove Contacts).
Message API	recipient_tag and recipient_subscription take a name or an ID. recipient_subscription also accepts the mandatory consent subscription.

Use the Contact API’s interests to set the tags and subscriptions of one contact as you create or update it. A list of names only adds; to remove an item, use the object form with "Unset". Use the Tag and Subscription APIs to add or remove many contacts for one tag or subscription.

Consent Is Separate

A contact’s consent_status decides whether Envoke may send them email at all; tags and subscriptions decide which messages they are in the audience for. Adding a contact to a subscription through the Contact API does not check their consent: a contact whose consent is Not Provided is added to the subscription like any other contact, and is then excluded when a message is sent to that subscription. See Consent fields for the consent types and when a change takes effect.

---

Send API or Message API

Both APIs send email, with different models.

The Send API (POST https://e1.envoke.com/v1/send) creates a message and sends it in the same request to recipients you list one by one. An address that matches no contact becomes a new contact and is sent the message. There is no draft, schedule, review, or cancel step.

The Message API (https://e1.envoke.com/v2/messages) creates a message as a Draft addressed to an audience Envoke already holds: a tag, a subscription, or a segment. Sending it, now or at a scheduled time, is a separate request that returns an estimate of the recipients, and a scheduled message can be cancelled.

	Send API	Message API
Recipients	Up to 1,000 email addresses or contact IDs per request, listed one by one. Further batches can be sent to the same message.	A tag, subscription, or segment, optionally narrowed by a subscription and by language.
Addresses that are not contacts	Created as contacts with your Transactional API consent, and sent the message.	Not applicable: only contacts in the audience are sent the message.
When it sends	Immediately.	Immediately, or at a send_time in your account’s time zone.
Review and cancel	None. A sent message cannot be changed or cancelled.	A Draft can be read, previewed at its preview_url, changed, or deleted. A Scheduled message can be cancelled back to Draft.
Counts in the response	The outcome for each recipient, decided when the request is made.	An estimate taken when the request is made; recipients are selected again when the send starts.
Personalisation	Per-recipient replace values, applied as each email is delivered. Envoke merge fields when enable_merge_fields is true.	replace values applied once when the message is saved, the same for every recipient. Envoke merge tags in the HTML for per-recipient content.
Tracking defaults	No open or click tracking unless track_recipient_activity is true. UTM parameters are never added.	utm_tag_links follows your account’s link analytics setting.
Needs before sending	The Transactional API preference (see Before Your First Send).	A subject, a sender, and at least one of recipient_subscription, recipient_tag, or recipient_segment.

Use the Send API when your system decides who receives a message, one person or a list of addresses, and the email goes out now: for example a confirmation or a notice to the people named in a request. Read the full rules in Send API - Fields Reference and Send API - Send.

Use the Message API when the audience is a tag, subscription, or segment in Envoke, or when the message needs a schedule, a review, or a cancel before it goes out. Sending with a future send_time returns the estimate and leaves the message Scheduled until then; see Message API - Sending.

Points that apply when you choose:

• Neither API accepts an idempotency key. Each Send API request and each POST https://e1.envoke.com/v2/messages/send (create and send) request creates a new message, so repeating one after a timeout can send the email twice. Sending an existing draft with POST https://e1.envoke.com/v2/messages/{ID}/send cannot send it twice: once sent, the message is no longer a Draft and a second request fails with Only 'Draft' messages can be updated, this message has the status: 'Scheduled' (or the message’s current status).
• Create and send can leave a draft behind. When POST https://e1.envoke.com/v2/messages/send creates the draft but the send step fails, the draft is kept and its ID is not returned. Give each message a unique name so the draft can be found with a name filter (see Create and send).
• Send API messages are also messages. A message sent through the Send API can be read, and deleted once its status is Sent, through the Message API, and its activity is in the Reports API under the id the Send API returned.

---

The Reports API and the Reports in Envoke

The Reports API returns the email activity counts behind the reports in Envoke as JSON. It is read-only, on /v2, and has no CSV format. The Message API returns no delivery, open, or click statistics; read them from the Reports API.

In Envoke	In the Reports API
The Sent message report of one message	Message Stats: GET https://e1.envoke.com/v2/reports/messages/{ID}
The folder report	The message activity list or the compare report with group_id, which includes subfolders at any depth
Clicking a count in the Sent message report to see its contacts	Message Contacts: GET https://e1.envoke.com/v2/reports/messages/{ID}/contacts
A contact’s Email sending history	Contact Activity: GET https://e1.envoke.com/v2/reports/contacts/{ID}

The numbers are not always the same as the Sent message report’s rows:

• Every metric counts distinct contacts. The Sent message report’s Opens and Bounced rows count one per contact per email client or bounce type, so they can be larger than the API’s opens and bounces (see How the counts work).
• A rate with nothing to divide by is null, where the Sent message report shows 0 (see Rates).
• Counts are read from a reporting copy of the database, so activity from the last few moments may not appear yet.
• Which messages are listed. The message activity list includes sent campaigns and automated messages. Drafts, scheduled messages, and messages with the Transactional status are not included (see Which messages are included).
• Times are in your account’s time zone, the zone the Envoke app and the Message API use.

On an account restricted from seeing contacts associated with email activity (the setting that hides a contact’s Email sending history in Envoke), the Contact Activity and Message Contacts endpoints return HTTP 403 (see Contact Activity errors), and the email_open and email_click webhook types cannot be subscribed to: they fail with Invalid webhook type: 'email_open'.

To receive each event as it happens instead of reading counts, subscribe to the email activity webhooks; see Hooks API - Webhook Payloads.

---

Before Your First Send

A send can be refused, or reach no one, because of account settings that are made in Envoke rather than through the API. Check each of these before your first send.

1. The API is enabled and your key works. See Before Your Key Works.
2. The Transactional API preference is set (Send API only). In Envoke, go to Account settings → Integrations → Transactional API and choose a Consent status and enter a Consent description. They are given to the contacts the Send API creates. Until they are set, every Send API request fails with A default consent status and description is required in order to use this API. The Message API does not use this preference.
3. A sender identity. Both APIs send from the account’s default sender identity unless the request names another one with sender. A Message API draft whose sender has been cleared cannot be sent: The field 'sender' must be set. Manage identities with the Sender API, which refuses addresses at free or personal email providers. Envoke does not check that an identity is verified before it sends; the Sender API’s dkim_status reports whether DKIM is configured for the identity’s domain, which improves deliverability.
4. Recipients whose consent allows sending. Apart from mandatory messages, existing contacts are sent a message only when their consent allows sending (for example Express, not Not Provided, Revoked, or Expired), their address is valid and has not been marked undeliverable, and, when your account requires email confirmation, they have confirmed it. The responses count each excluded recipient by reason (see Consent and Recipient counts).
5. The mandatory consent subscription (mandatory messages only). A mandatory message, sent with is_mandatory: true on the Send API or to the mandatory consent subscription as recipient_subscription on the Message API, reaches only contacts who hold that subscription, whatever their consent status, except contacts who have reported spam. Contacts who do not hold it are excluded as excluded_mandatory_consent on the Send API.
6. Credits. A prepaid account needs a credit balance at least as large as the number of emails to be sent; otherwise the Send API fails with Message not sent, the account is out of credits and the Message API with 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 Message not sent, the account has not upgraded or Email can't be sent, the account has not upgraded.

For a walkthrough that creates a contact, a template, and a webhook subscription and then sends, see Your first integration.

---

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.