{ "openapi": "3.1.0", "info": { "title": "Envoke Send API", "version": "1.0.0", "description": "Create one email message and send it immediately to a list of recipients, in a single request. The Send API has one endpoint, `POST /send`, on `/v1` only. There is no draft, schedule, review, or cancel step: when the request succeeds, the emails are already queued for delivery. Points a client must know: (1) One request creates one message and sends it to up to 1,000 recipients, given either by email address (`recipients`) or by Envoke contact ID (`recipient_contact_ids`); when both are sent, `recipient_contact_ids` wins and `recipients` is ignored. (2) An email address that matches no contact becomes a new contact and is sent the message; the contact is created at once with its email address only, and its consent (the consent status and description from the account's Transactional API preference), its `api_insert` contact event, and the account's new-contact automation are added by a background process, usually within a minute; until then the Contact API does not return the contact (a lookup by email or ID returns `[]`). (3) The Transactional API preference must be set first (Account settings, Integrations, Transactional API: a consent status and a consent description); until it is, every request fails with `A default consent status and description is required in order to use this API`. (4) Who is sent the message is decided when the request is made, from each recipient's consent and address status: existing contacts are sent only when their consent allows it and their address is not bounced or (with double opt-in) unconfirmed; valid new addresses are always sent. With `is_mandatory`, existing contacts are sent only when they hold the account's mandatory consent subscription. (5) The success response is `result_text` `Message is sending` with `result_data` holding the new message's `id` as an integer, `new_contacts_created`, a `summary` of counts (each recipient counted once, under the first reason that applies), and one entry per recipient in `recipients`, in the order of the request. A request succeeds when at least one recipient is sent the message; when none can be, nothing is created and the response is HTTP 400 `Message not sent, there are no valid recipients` with the counts and entries but no `id`. (6) To send the same message to more than 1,000 people, send further batches of up to 1,000 with `id` set to the first response's `id` and only `recipients` beside it; `id` is echoed with the JSON type it was sent with. (7) The message can be read, and deleted once its status is `Sent`, through the Message API (`/v2/messages/{id}`), where its `id` is a string. (8) Validation errors return `result_text` `Validation failed, see 'result_data' -> 'errors'` with `result_data.errors` as an array of strings; four checks return a single error at once (the Transactional API preference, the size of `html`, a `template_id` that is not found, and neither `html` nor `template_id`) and all others are collected; an unknown `group`, `sender`, `reply_to`, or `language` also returns `result_data.allowed_values` when the account has 50 or fewer options. Plain errors (`Invalid JSON`, `Invalid request`, `Message content error`) use `result_data: []`; `Internal error; please contact Envoke support` has no `result_data` key. Every error uses HTTP 400, except authentication and account errors: invalid credentials return 401 with `result_text` `Invalid credentials` and `result_data: []`; a valid key on a closed or inactive account returns 403 with the plain-text body `This account has been closed.` or `This account is not active.`; exceeding the account's API limit returns 429 with `success: false` and a `result_text` naming the limit." }, "servers": [ { "url": "https://e1.envoke.com/v1", "description": "Production" } ], "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Send", "description": "Create a message and send it now, or send an existing Send API message to more recipients." } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic Auth. Use your API ID as the username and API Key as the password. See https://developers.envoke.com/guides/authentication/." } }, "schemas": { "Replace": { "type": "object", "description": "Placeholder text to replace in the message HTML for one recipient, on a recipient object only (there is no request-level `replace`). The replacement is made when each email is delivered; the stored message keeps its placeholders, so the HTML read through the Message API still shows them, and a later batch sent with `id` can fill the same placeholders with new values. Every key must start with `{` and end with `}`; every value must be a string and is inserted as is, without escaping, so it can contain HTML. A key that does not appear in the HTML is ignored. Keys are applied in the order sent, so a later key can match text inserted by an earlier value. A key may not contain `{@pref-`, `{@consent-url`, or `{@consent-prefpage-url`. `{}` is ignored and the recipient is sent the HTML unchanged. `replace` runs before merge fields: with `enable_merge_fields` on, merge tags inside a value are filled in too, and a merge tag used as a key (such as `{@first_name}`) is replaced by the value instead. Only the HTML is changed, not the subject. Any other shape (a list, a non-string value, a key without braces, a protected key) does not fail the request: that recipient is excluded with `excluded_invalid_replace_data`, and no contact is created for a new address.", "propertyNames": { "pattern": "^\\{.+\\}$" }, "additionalProperties": { "type": "string" }, "examples": [ { "{BOAT_NAME}": "Heron", "{SEAT}": "8 (stroke)", "{CALL_TIME}": "6:15 a.m." } ] }, "Recipient": { "description": "An item of `recipients`: an email address, or an object with `email` and optional `replace`. Only the first item decides the form: if it is a string, every item is read as an address; if it is an object, every item must be an object. Use the same form for the whole list. An object first item without `email` fails with `Invalid 'recipients': items must have the field 'email'`; a later object without `email` is not sent and is returned as `{\"missing_key_field\": true}`. Other keys on an object, such as `first_name`, are ignored: contact details cannot be set through this API. Each address is matched against the account's contacts; send each address once, spelled exactly as it is stored in Envoke, because a repeated item and an address in a different letter case are treated as separate recipients.", "oneOf": [ { "type": "string", "description": "An email address.", "examples": [ "stroke.seat@example.org" ] }, { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "The recipient's email address.", "examples": [ "stroke.seat@example.org" ] }, "replace": { "$ref": "#/components/schemas/Replace" } } } ] }, "RecipientById": { "description": "An item of `recipient_contact_ids`: a contact ID (an integer or a numeric string), or an object with `id` and optional `replace`. The first-item rule of `Recipient` applies: an object first item without `id` fails with `Invalid 'recipient_contact_ids': items must have the field 'id'`, and a later object without `id` is returned as `{\"missing_key_field\": true}`. An ID that matches no contact in the account is not sent and is returned as `{\"excluded_invalid_ids\": true}`. No contacts are created.", "oneOf": [ { "type": "integer", "minimum": 1, "examples": [ 7001 ] }, { "type": "string", "pattern": "^[0-9]+$", "examples": [ "7001" ] }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": [ "integer", "string" ], "description": "The contact ID.", "examples": [ 7001 ] }, "replace": { "$ref": "#/components/schemas/Replace" } } } ] }, "SendRequest": { "type": "object", "description": "Create a message and send it now. `subject` is required, with one of `html` or `template_id` and one of `recipients` or `recipient_contact_ids`. Every field is write-only; the response returns the message `id`, counts, and one entry per recipient, not the fields sent. Any other key fails with `'{field}' is not a valid field`: this includes `send_time` (every send is immediate), `utm_tag_links` (UTM tracking parameters are never added), `preheader_text`, a top-level `replace`, and `recipient_subscription`, `recipient_tag`, `recipient_segment`, and `recipient_language` (to send to a tag, subscription, or segment, use the Message API). `id` set to `0`, `\"\"`, or `null` counts as not sent. Defaults: `name` `API Message {Y-m-d H:i:s}` from Envoke's server clock; `group` `API Messages`; `sender` the account's default sender; no `reply_to`; `language` `en` (not the account's default language); `is_mandatory`, `track_recipient_activity`, `enable_merge_fields`, and `publish_archive` `false`.", "required": [ "subject" ], "allOf": [ { "anyOf": [ { "required": [ "html" ] }, { "required": [ "template_id" ] } ] }, { "anyOf": [ { "required": [ "recipients" ] }, { "required": [ "recipient_contact_ids" ] } ] } ], "properties": { "name": { "type": "string", "minLength": 3, "description": "Internal name shown in the Envoke message list and in the Message API; recipients do not see it. At least 3 characters: `The field 'name' must be at least 3 characters long`. A name longer than 300 characters is cut to its first 300 without an error. Default `API Message {Y-m-d H:i:s}`, from Envoke's server clock, which can differ from the account time zone.", "examples": [ "Head of the Valley - Crew Call-up" ] }, "subject": { "type": "string", "minLength": 6, "description": "Subject line. Missing or empty: `The field 'subject' must be set`. Shorter than 6 characters: `The field 'subject' must be at least 6 characters long`; `\"\"` returns both errors. A subject longer than 360 characters is cut to its first 360 without an error. Required even with `template_id`, because a template's subject is not copied. Per-recipient `replace` does not change it.", "examples": [ "Crew call-up: Head of the Valley" ] }, "group": { "type": [ "string", "integer" ], "description": "Name or ID of an existing message group (folder). Names are matched ignoring case, with a space and an underscore treated as the same. Only message groups are accepted, and a group is not created automatically: an unknown value fails with `Invalid 'group': '{value}'` and `allowed_values.group`. `\"\"` or `\"0\"` uses the default. Default: the `API Messages` group, which Envoke creates the first time it is needed; in Envoke its messages are shown in the `API Messages` folder and left out of the All folder and the status folders. A message with a custom group appears in that group's folder and also in All.", "examples": [ "Crew Notices", 41 ] }, "sender": { "type": [ "string", "integer" ], "description": "A sender identity, resolved in this order: an identity ID (`512` or `\"512\"`); `Name ` matching an identity, ignoring case and treating a space and an underscore as the same; `\"\"` or `\"0\"` (not set, so the default applies); an email address, matched exactly including case against the first identity with that address, else `No sender identity found for email: '{value}'`; anything else gives `Invalid 'sender': '{value}'`. Both errors include `allowed_values.sender`, keyed by ID, as `Name `. Default: the identity marked as the account default. The identity is used as configured.", "examples": [ "Boathouse ", "boathouse@example.org", 512 ] }, "reply_to": { "type": [ "string", "integer" ], "description": "Same formats and resolution as `sender`; errors read `No reply_to identity found for email: '{value}'` and `Invalid 'reply_to': '{value}'`. No default: when not set, replies go to the sender address.", "examples": [ 513 ] }, "language": { "type": [ "string", "integer" ], "description": "The language the message is written in: `en` or `fr` (case-insensitive), or the IDs `1` (English) or `3` (French). `\"\"` or `\"0\"` sets `en`. Envoke uses it for the text it adds, such as the unsubscribe footer and merge fields; it does not choose recipients. Any other value fails with `Invalid 'language': '{value}'` and `allowed_values.language` `{\"1\":\"en\",\"3\":\"fr\"}`. Default `en`, not the account's default language.", "examples": [ "fr" ] }, "is_mandatory": { "type": [ "boolean", "string", "integer" ], "description": "Send as a mandatory consent message. `true`, `\"true\"`, `1`, `\"1\"`, `\"yes\"`, or `\"on\"` is true; anything else is `false`, with no error. When true, the message is sent as a consent-exempt message with the mandatory subscription's description, in the message's language, as the stated reason, and existing contacts are sent only when they hold the account's mandatory consent subscription and have not reported the account's email as spam; a contact without it is counted as `excluded_mandatory_consent`, and one who holds it but has reported spam as `excluded_unsubscribed_contacts`. New addresses are created with the Transactional API consent, given the mandatory subscription, and sent the message. When the account has no mandatory consent subscription, every existing contact is excluded as `excluded_mandatory_consent` and the message is not marked consent-exempt. The `excluded_mandatory_consent` summary count appears only when this is true. Default `false`.", "examples": [ true ] }, "track_recipient_activity": { "type": [ "boolean", "string", "integer" ], "description": "Accepted values as for `is_mandatory`. When true, links are rewritten to record clicks and an open-tracking image is added; when false, links are left as written and no image is added. Default `false`.", "examples": [ true ] }, "enable_merge_fields": { "type": [ "boolean", "string", "integer" ], "description": "Accepted values as for `is_mandatory`. When true, all Envoke merge fields (such as `{@first_name}`) and the older `{fname}`-style tags are replaced. When false, only these are replaced: `{@pref-0}`, `{@pref-1}`, `{@consent-url}`, and `{@consent-prefpage-url}` (the link to the recipient's email preferences page), `{fname}` and `{lname}` (the contact's names), and `{eid}` (the contact's `external_id`). Either way, when the HTML contains none of `{@pref-`, `{@consent-url`, or `{@consent-prefpage-url`, Envoke adds its standard unsubscribe footer to every email; tags inserted through `replace` values do not count. Default `false`.", "examples": [ true ] }, "publish_archive": { "type": [ "boolean", "string", "integer" ], "description": "Accepted values as for `is_mandatory`. When true, the message is published to the account's public message archive. Default `false`.", "examples": [ true ] }, "html": { "type": "string", "maxLength": 204800, "description": "The complete message HTML, stored as sent without checks. Over 200 kB (204,800 bytes) fails with `The field 'html' may not be longer than 200kB`; only the `html` sent is checked, not HTML copied through `template_id` or the HTML after `replace`. `\"\"` counts as not sent. When both `html` and `template_id` are sent, `html` is used and `template_id` is ignored, with no error. HTML containing the `

You are racing in {BOAT_NAME}, seat {SEAT}.

" ] }, "template_id": { "type": [ "integer", "string" ], "description": "ID of a template, or of another message in the account (including an earlier Send API message), whose HTML the new message copies; templates shared with the account can be used too. A numeric string such as `\"1951\"` is accepted. Only the HTML (and which editor the content opens in) is copied; the subject, sender, reply-to, language, and group are not. The copy is independent of later changes to the source. An ID that matches nothing fails with `Nothing found for 'template_id': {value}`. `0`, `\"0\"`, and `\"\"` count as not sent.", "examples": [ 1951, "1951" ] }, "recipients": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "Up to 1,000 email addresses or recipient objects. Missing or `[]`: `The field 'recipients' must be set`. Not a list: `The field 'recipients' must be an array`. More than 1,000: `The field 'recipients' may not contain more than 1000`; every item counts toward the limit, including invalid ones and repeats, and exactly 1,000 is allowed. An address that matches no contact becomes a new contact and is sent the message; an invalid address is not sent and no contact is created.", "items": { "$ref": "#/components/schemas/Recipient" } }, "recipient_contact_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "Up to 1,000 contact IDs or recipient objects. Wins over `recipients` when both are sent. `[]`: `The field 'recipient_contact_ids' must not be empty`. Not a list: `The field 'recipient_contact_ids' must be an array`. More than 1,000: `The field 'recipient_contact_ids' may not contain more than 1000`.", "items": { "$ref": "#/components/schemas/RecipientById" } } }, "additionalProperties": false }, "SendToExistingRequest": { "type": "object", "description": "Send an existing Send API message to more recipients. Only `id` and `recipients` may be sent. Checks, in order: the Transactional API preference; the message must exist in the account and not be deleted (`No message found for 'id': {id}`, with the value as sent; a template is not found either); it must have been created by the Send API (`Only messages created by the API are valid when providing an 'id'`); then any other field fails with `The field '{field}' is not valid when providing an 'id'`, or for several `The fields '{f1}', '{f2}' are not valid when providing an 'id'`. This includes `recipient_contact_ids`, so recipients are added by email address. The field errors and the `recipients` shape errors are returned together, without `allowed_values`. Recipients take the same forms, limit, and checks as a new message, including per-recipient `replace`, new contacts for unknown addresses, and the consent rules; a message first sent with `is_mandatory` is sent as a mandatory message again. The message's content, subject, sender, reply-to, language, group, tracking, and merge field settings are reused and cannot be changed. Its status is unchanged: a message that is already `Sent` stays `Sent` while the new batch is delivered.", "required": [ "id", "recipients" ], "properties": { "id": { "type": [ "integer", "string" ], "description": "The ID of a message created by the Send API. Echoed in the response with its JSON type unchanged.", "examples": [ 3006, "3006" ] }, "recipients": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "As `recipients` on a new message.", "items": { "$ref": "#/components/schemas/Recipient" } } }, "additionalProperties": false }, "SendSummary": { "type": "object", "description": "One count per outcome, all integers. The counts are exclusive: each recipient is counted once, under the first reason that applies, in the order bounced, consent, unverified, invalid address, invalid `replace`. So `emails_to_be_sent` plus the `excluded_` counts equals `total_selected`, except that items missing their key field are counted in `total_selected` only. Keys appear in the order listed here; some are present only in certain requests.", "required": [ "total_selected", "emails_to_be_sent", "excluded_unsubscribed_contacts", "excluded_bounced_emails", "excluded_unverified_emails" ], "properties": { "total_selected": { "type": "integer", "description": "Always present. Every item in the recipient list.", "examples": [ 4 ] }, "emails_to_be_sent": { "type": "integer", "description": "Always present. Recipients who are sent the message, existing and new: the number of emails queued.", "examples": [ 2 ] }, "excluded_unsubscribed_contacts": { "type": "integer", "description": "Always present. Existing contacts whose consent does not allow sending, such as `Not Provided`, `Revoked`, or `Expired`.", "examples": [ 1 ] }, "excluded_invalid_emails": { "type": "integer", "description": "Present when the request uses `recipients`. Addresses that are not valid, whether new or stored on an existing contact.", "examples": [ 1 ] }, "excluded_invalid_ids": { "type": "integer", "description": "Present when the request uses `recipient_contact_ids`, in place of `excluded_invalid_emails`. IDs that match no contact in the account.", "examples": [ 1 ] }, "excluded_bounced_emails": { "type": "integer", "description": "Always present. Existing contacts whose address has been marked undeliverable.", "examples": [ 0 ] }, "excluded_unverified_emails": { "type": "integer", "description": "Always present. Existing contacts who have not confirmed their address, when the account requires confirmation (double opt-in); otherwise `0`.", "examples": [ 0 ] }, "excluded_invalid_replace_data": { "type": "integer", "description": "Present only when at least one recipient had an invalid `replace`. Recipients excluded for it.", "examples": [ 1 ] }, "excluded_mandatory_consent": { "type": "integer", "description": "Present only when `is_mandatory` is true (or when `id` names a message first sent with it). Existing contacts who do not hold the account's mandatory consent subscription.", "examples": [ 1 ] } }, "additionalProperties": false }, "RecipientResult": { "description": "One entry per recipient, in the order of the request. `id` is the contact ID, an integer, for existing and new contacts. `email` is the address as stored on the contact for an existing contact, and as sent for a new address. Entries are keyed by the stored address, so a recipient listed more than once has a single entry.", "oneOf": [ { "title": "Existing contact, sent", "type": "object", "required": [ "id", "email", "emails_to_be_sent" ], "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "emails_to_be_sent": { "const": true } }, "additionalProperties": false }, { "title": "Existing contact, excluded", "type": "object", "description": "`id`, `email`, and exactly one exclusion key.", "required": [ "id", "email" ], "minProperties": 3, "maxProperties": 3, "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "excluded_bounced_emails": { "const": true }, "excluded_unsubscribed_contacts": { "const": true }, "excluded_mandatory_consent": { "const": true }, "excluded_unverified_emails": { "const": true }, "excluded_invalid_emails": { "const": true }, "excluded_invalid_replace_data": { "const": true } }, "additionalProperties": false }, { "title": "New address, created and sent", "type": "object", "required": [ "id", "email", "new_contacts_created", "emails_to_be_sent" ], "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "new_contacts_created": { "const": true }, "emails_to_be_sent": { "const": true } }, "additionalProperties": false }, { "title": "New address, not valid", "type": "object", "description": "No contact is created.", "required": [ "email", "excluded_invalid_emails" ], "properties": { "email": { "type": "string" }, "excluded_invalid_emails": { "const": true } }, "additionalProperties": false }, { "title": "New address, invalid replace", "type": "object", "description": "No contact is created.", "required": [ "email", "excluded_invalid_replace_data" ], "properties": { "email": { "type": "string" }, "excluded_invalid_replace_data": { "const": true } }, "additionalProperties": false }, { "title": "ID not found", "type": "object", "description": "The ID is not repeated; match it by position.", "required": [ "excluded_invalid_ids" ], "properties": { "excluded_invalid_ids": { "const": true } }, "additionalProperties": false }, { "title": "Object without its key field", "type": "object", "description": "A later recipient object without `email` (or `id`). Counted in `total_selected` only.", "required": [ "missing_key_field" ], "properties": { "missing_key_field": { "const": true } }, "additionalProperties": false } ], "examples": [ { "id": 7001, "email": "stroke.seat@example.org", "emails_to_be_sent": true }, { "id": 7003, "email": "cox@example.org", "excluded_unsubscribed_contacts": true }, { "id": 7005, "email": "novice.rower@example.org", "new_contacts_created": true, "emails_to_be_sent": true }, { "email": "kvrc-not-an-email", "excluded_invalid_emails": true }, { "excluded_invalid_ids": true } ] }, "SendSuccessResponse": { "type": "object", "description": "At least one recipient was sent the message. HTTP 200. The emails are already queued. No dates are returned.", "required": [ "success", "result_text", "result_data" ], "properties": { "success": { "type": "boolean", "const": true }, "result_text": { "type": "string", "const": "Message is sending" }, "result_data": { "type": "object", "required": [ "id", "new_contacts_created", "summary", "recipients" ], "properties": { "id": { "type": [ "integer", "string" ], "description": "The new message's ID, an integer. When the request sends `id`, this echoes the value as sent, with its JSON type unchanged (`3006` returns `3006`, `\"3006\"` returns `\"3006\"`). The Message API returns the same message's `id` as a string.", "examples": [ 3001 ] }, "new_contacts_created": { "type": "integer", "minimum": 0, "description": "Number of addresses created as new contacts. Always `0` with `recipient_contact_ids`.", "examples": [ 0 ] }, "summary": { "$ref": "#/components/schemas/SendSummary" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResult" } } }, "additionalProperties": false } } }, "NoValidRecipientsResponse": { "type": "object", "description": "No recipient could be sent the message. HTTP 400. No message is created. `result_data` has `summary` and `recipients` only: no `id`, no `new_contacts_created`, and no `errors` key. A valid new address without an invalid `replace` is always sent, so a request with one never ends this way.", "required": [ "success", "result_text", "result_data" ], "properties": { "success": { "type": "boolean", "const": false }, "result_text": { "type": "string", "const": "Message not sent, there are no valid recipients" }, "result_data": { "type": "object", "required": [ "summary", "recipients" ], "properties": { "summary": { "$ref": "#/components/schemas/SendSummary" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResult" } } }, "additionalProperties": false } } }, "ValidationErrorResponse": { "type": "object", "description": "Validation errors, HTTP 400. Also used for the empty-body error, the `id` errors, and the credit errors (`Message not sent, the account is out of credits`, `Message not sent, the account has not upgraded`). `allowed_values` is present only when `group`, `sender`, `reply_to`, or `language` had an unknown value and the account has 50 or fewer options for it; it is never returned when `id` is sent.", "required": [ "success", "result_text", "result_data" ], "properties": { "success": { "type": "boolean", "const": false }, "result_text": { "type": "string", "const": "Validation failed, see 'result_data' -> 'errors'" }, "result_data": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "allowed_values": { "type": "object", "description": "Keyed by field name; each value is an object of the valid options keyed by ID. Sender and reply-to options are `Name `.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } }, "examples": [ { "group": { "41": "Crew Notices", "42": "API Messages" } } ] } }, "additionalProperties": false } } }, "PlainErrorResponse": { "type": "object", "description": "Request-shape and content errors: the message is in `result_text` and `result_data` is an empty array. HTTP 400 (401 for invalid credentials).", "required": [ "success", "result_text", "result_data" ], "properties": { "success": { "type": "boolean", "const": false }, "result_text": { "type": "string", "examples": [ "Invalid JSON", "Invalid request", "Message content error" ] }, "result_data": { "type": "array", "maxItems": 0 } } }, "InternalErrorResponse": { "type": "object", "description": "The message or its recipients could not be saved. HTTP 400, with no `result_data` key at all. Contact Envoke support if it persists.", "required": [ "success", "result_text" ], "properties": { "success": { "type": "boolean", "const": false }, "result_text": { "type": "string", "const": "Internal error; please contact Envoke support" } }, "additionalProperties": false } }, "responses": { "Unauthorized": { "description": "Invalid API ID or key. A `WWW-Authenticate: Basic` header is sent, and the body is the plain error envelope. The response's `Content-Type` is `text/html`, although the body is JSON.", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/PlainErrorResponse" }, "example": { "success": false, "result_data": [], "result_text": "Invalid credentials" } } } }, "Forbidden": { "description": "Valid key on a closed or inactive account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "result_data": { "type": "array", "maxItems": 0 }, "result_text": { "type": "string", "enum": [ "This account has been closed.", "This account is not active." ] } }, "required": [ "success", "result_data", "result_text" ] } } } }, "TooManyRequests": { "description": "The account's API limit was exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "result_text": { "type": "string", "description": "Names the limit that was exceeded." }, "result_data": { "type": "object" } } } } } } } }, "paths": { "/send": { "post": { "summary": "Send a message", "description": "Creates a message and sends it now to up to 1,000 recipients, or, with `id`, sends an existing Send API message to up to 1,000 more. The body is a JSON object. No body, an empty body, `{}`, `[]`, or `null` returns `Request body may not be empty`; a body that is not valid JSON returns the plain error `Invalid JSON`. A successful request creates the message with status `Sending`, decides who is sent it, and queues the emails straight away; Envoke checks every minute for messages whose emails have all been handed off and marks them `Sent`. Order of checks on a new message: the Transactional API preference, the size of `html`, `template_id` not found, neither `html` nor `template_id` (each returned alone); then the subject, recipient, and field errors (collected and returned together); then each recipient is looked up and new addresses are created as contacts; then the credit check (a prepaid account whose balance is lower than `emails_to_be_sent` gets `Message not sent, the account is out of credits`; a monthly-billed account not yet on a paid plan, with too few credits, gets `Message not sent, the account has not upgraded`); then, when nobody can be sent the message, `Message not sent, there are no valid recipients`. The message is then readable through the Message API: `GET /v2/messages/{id}` shows `status` `Sending`, then `Sent`; `group` `API Messages` (or the group set); `send_time` the time of the request; `utm_tag_links` `false`; and `recipient_subscription`, `recipient_tag`, `recipient_segment`, and `recipient_language` empty, except that a mandatory message shows the mandatory consent subscription in `recipient_subscription`. With `include_html=1` the HTML still shows the `replace` placeholders. The Message API refuses to update or send it, because it is not a `Draft`; it can be deleted with `DELETE /v2/messages/{id}` once it is `Sent` (while it is `Sending`, delete fails with `Message: '{name}' is currently sending`), after which it can no longer be used with `id`. Only `POST /v1/send` (and `POST /v1/send.json`) exists.", "operationId": "sendEmail", "tags": [ "Send" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SendRequest" }, { "$ref": "#/components/schemas/SendToExistingRequest" } ] }, "examples": { "html_one_address": { "summary": "Send HTML to one address, with every default", "value": { "subject": "Practice moved to 6:00 a.m.", "html": "

Tomorrow's practice starts at 6:00 a.m. at the boathouse.

", "recipients": [ "stroke.seat@example.org" ] } }, "replace_per_recipient": { "summary": "Personalise each email with replace", "value": { "name": "Head of the Valley - Crew Call-up", "subject": "Crew call-up: Head of the Valley", "sender": "Boathouse ", "html": "

You 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." } } ] } }, "template_with_merge_fields": { "summary": "Copy a template's HTML and fill it in, with merge fields", "value": { "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." } } ] } }, "contact_ids": { "summary": "Send to contacts by ID", "value": { "subject": "Erg test results are posted", "html": "

Your erg test results are on the club board.

", "recipient_contact_ids": [ 7001, 7002, 7009 ] } }, "contact_ids_with_replace": { "summary": "Send to contacts by ID, each with its own replace values", "value": { "subject": "Your seat for Saturday", "html": "

Saturday you are in seat {SEAT}.

", "recipient_contact_ids": [ { "id": 7001, "replace": { "{SEAT}": "8" } }, { "id": 7002, "replace": { "{SEAT}": "1" } } ] } }, "every_option": { "summary": "Set every option", "value": { "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" ] } }, "mandatory": { "summary": "Send a mandatory message", "value": { "name": "Updated Water Safety Policy", "subject": "Updated water safety policy for all members", "is_mandatory": true, "html": "

The club's water safety policy has changed. Please read it before your next outing.

", "recipients": [ "stroke.seat@example.org", "bow.seat@example.org" ] } }, "mixed": { "summary": "Existing, new, unsubscribed, and invalid recipients", "value": { "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" ] } }, "add_recipients": { "summary": "Send an existing Send API message to more recipients", "value": { "id": 3006, "recipients": [ "bow.seat@example.org", "novice.rower@example.org" ] } }, "add_recipients_with_replace": { "summary": "A later batch fills the stored placeholders with new values", "value": { "id": 3002, "recipients": [ { "email": "spare.rower@example.org", "replace": { "{BOAT_NAME}": "Osprey", "{SEAT}": "4", "{CALL_TIME}": "7:00 a.m." } } ] } } } } } }, "responses": { "200": { "description": "At least one recipient was sent the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSuccessResponse" }, "examples": { "one_address": { "summary": "One existing contact, sent", "value": { "success": true, "result_text": "Message is sending", "result_data": { "id": 3001, "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": 7001, "email": "stroke.seat@example.org", "emails_to_be_sent": true } ] } } }, "contact_ids": { "summary": "By contact ID; 7009 does not exist", "value": { "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 } ] } } }, "mandatory": { "summary": "Mandatory: 7002 does not hold the mandatory consent subscription", "value": { "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 } ] } } }, "mixed": { "summary": "One existing and one new contact sent; one unsubscribed; one invalid", "value": { "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 } ] } } }, "invalid_replace": { "summary": "One recipient excluded for an invalid replace", "value": { "success": true, "result_text": "Message is sending", "result_data": { "id": 3002, "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_invalid_replace_data": 1 }, "recipients": [ { "id": 7001, "email": "stroke.seat@example.org", "emails_to_be_sent": true }, { "id": 7002, "email": "bow.seat@example.org", "excluded_invalid_replace_data": true } ] } } }, "add_recipients": { "summary": "Existing message 3006 sent to one more contact", "value": { "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 } ] } } }, "add_recipients_string_id": { "summary": "`id` sent as a string is echoed as a string", "value": { "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 } ] } } } } } } }, "400": { "description": "Validation error, no valid recipients, a request-shape or content error, or an internal error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationErrorResponse" }, { "$ref": "#/components/schemas/NoValidRecipientsResponse" }, { "$ref": "#/components/schemas/PlainErrorResponse" }, { "$ref": "#/components/schemas/InternalErrorResponse" } ] }, "examples": { "empty_body": { "summary": "No body, an empty body, {}, [], or null", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Request body may not be empty" ] } } }, "preference_not_set": { "summary": "The Transactional API preference is not set (returned alone)", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "A default consent status and description is required in order to use this API" ] } } }, "html_too_large": { "summary": "html over 204,800 bytes (returned alone)", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'html' may not be longer than 200kB" ] } } }, "template_not_found": { "summary": "No template or message with that ID (returned alone)", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Nothing found for 'template_id': 1999" ] } } }, "no_content": { "summary": "Neither html nor template_id (returned alone)", "value": { "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" ] } } }, "collected": { "summary": "Field errors returned together", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'subject' must be set", "The field 'recipients' must be set", "The field 'name' must be at least 3 characters long", "'send_time' is not a valid field" ] } } }, "subject_empty": { "summary": "subject \"\" returns both subject errors", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'subject' must be set", "The field 'subject' must be at least 6 characters long" ] } } }, "not_supported": { "summary": "Keys that are not Send API fields", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "'send_time' is not a valid field", "'utm_tag_links' is not a valid field", "'replace' is not a valid field" ] } } }, "unknown_group": { "summary": "Unknown group, with allowed_values", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Invalid 'group': 'Regattas'" ], "allowed_values": { "group": { "41": "Crew Notices", "42": "API Messages" } } } } }, "sender_not_found": { "summary": "No identity has that address", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "No sender identity found for email: 'regatta@example.org'" ], "allowed_values": { "sender": { "512": "Boathouse ", "513": "Head Coach " } } } } }, "unknown_language": { "summary": "Unknown language", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Invalid 'language': 'de'" ], "allowed_values": { "language": { "1": "en", "3": "fr" } } } } }, "recipients_shape": { "summary": "First recipient object without email", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Invalid 'recipients': items must have the field 'email'" ] } } }, "id_not_found": { "summary": "id matches no message in the account (returned alone)", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "No message found for 'id': 3099" ] } } }, "id_not_api": { "summary": "id is a message not created by the Send API (returned alone)", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Only messages created by the API are valid when providing an 'id'" ] } } }, "id_with_field": { "summary": "Another field sent with id", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'subject' is not valid when providing an 'id'" ] } } }, "id_with_contact_ids": { "summary": "recipient_contact_ids is not accepted with id", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The field 'recipient_contact_ids' is not valid when providing an 'id'" ] } } }, "id_with_fields": { "summary": "Several other fields sent with id", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "The fields 'subject', 'html' are not valid when providing an 'id'" ] } } }, "out_of_credits": { "summary": "Prepaid balance lower than emails_to_be_sent", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Message not sent, the account is out of credits" ] } } }, "not_upgraded": { "summary": "Monthly-billed account not yet on a paid plan, with too few credits", "value": { "success": false, "result_text": "Validation failed, see 'result_data' -> 'errors'", "result_data": { "errors": [ "Message not sent, the account has not upgraded" ] } } }, "no_valid_recipients": { "summary": "Nobody can be sent the message; nothing is created", "value": { "success": false, "result_text": "Message not sent, there are no valid recipients", "result_data": { "summary": { "total_selected": 2, "emails_to_be_sent": 0, "excluded_unsubscribed_contacts": 1, "excluded_invalid_emails": 1, "excluded_bounced_emails": 0, "excluded_unverified_emails": 0 }, "recipients": [ { "id": 7003, "email": "cox@example.org", "excluded_unsubscribed_contacts": true }, { "email": "kvrc-not-an-email", "excluded_invalid_emails": true } ] } } }, "invalid_json": { "summary": "The body is not valid JSON", "value": { "success": false, "result_data": [], "result_text": "Invalid JSON" } }, "invalid_request": { "summary": "The request could not be processed", "value": { "success": false, "result_data": [], "result_text": "Invalid request" } }, "content_error": { "summary": "The content could not be saved", "value": { "success": false, "result_data": [], "result_text": "Message content error" } }, "internal_error": { "summary": "The message or its recipients could not be saved (no result_data key)", "value": { "success": false, "result_text": "Internal error; please contact Envoke support" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } } }