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/V1SendSendSuccessResponse"
},
"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/V1SendValidationErrorResponse"
},
{
"$ref": "#/components/schemas/NoValidRecipientsResponse"
},
{
"$ref": "#/components/schemas/V1SendPlainErrorResponse"
},
{
"$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/V1SendUnauthorized"
},
"403": {
"$ref": "#/components/responses/V1SendForbidden"
},
"429": {
"$ref": "#/components/responses/V1SendTooManyRequests"
}
}
}
},
"/v1/senders": {
"get": {
"summary": "List sender identities",
"description": "Returns a paginated array of sender identities for the authenticated account. Supports filtering by id, name, email, and is_default. Note: sorting is not currently supported.",
"operationId": "listSenders",
"tags": [
"Senders"
],
"parameters": [
{
"$ref": "#/components/parameters/V1SendersLimit"
},
{
"$ref": "#/components/parameters/V1SendersSkip"
},
{
"$ref": "#/components/parameters/V1SendersFields"
},
{
"$ref": "#/components/parameters/V1SendersResultType"
},
{
"name": "filter[id]",
"in": "query",
"description": "Filter by sender ID. Supports operators: `(ne)`.",
"schema": {
"type": "string"
}
},
{
"name": "filter[name]",
"in": "query",
"description": "Filter by sender display name. Supports operators: `(ne)`.",
"schema": {
"type": "string"
}
},
{
"name": "filter[email]",
"in": "query",
"description": "Filter by sender email address. Supports operators: `(ne)`.",
"schema": {
"type": "string"
}
},
{
"name": "filter[is_default]",
"in": "query",
"description": "Filter by default status. Use 1 to return only the default sender, 0 to return only non-default senders.",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
}
],
"responses": {
"200": {
"description": "A list of sender identities.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Sender"
}
},
{
"type": "object",
"description": "Key-value map of sender ID to name.",
"additionalProperties": {
"type": "string"
}
}
]
},
"examples": {
"array": {
"summary": "Default array response",
"value": [
{
"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
}
]
},
"kvp": {
"summary": "Key-value pair response (result_type=kvp)",
"value": {
"1": "City of Harborview",
"2": "Parks & Recreation"
}
},
"empty": {
"summary": "No senders found",
"value": []
}
}
}
}
},
"400": {
"description": "Invalid query parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1SendersValidationErrorResponse"
}
}
}
}
}
},
"post": {
"summary": "Create a sender identity",
"description": "Creates a new sender identity. Both name and email are required. The first identity created is automatically set as the account's default.",
"operationId": "createSender",
"tags": [
"Senders"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SenderCreate"
},
"examples": {
"basic": {
"summary": "Create a sender identity",
"value": {
"name": "City of Harborview",
"email": "communications@harborview.gov"
}
},
"department": {
"summary": "Create a department sender",
"value": {
"name": "Parks & Recreation",
"email": "parks@harborview.gov"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Sender created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1SendersCreateSuccessResponse"
},
"example": {
"success": true,
"result_text": "Created",
"result_data": {
"id": "1",
"name": "City of Harborview",
"email": "communications@harborview.gov",
"is_default": true,
"dkim_status": {
"verified": true,
"domain": "harborview.gov"
}
}
}
}
}
},
"400": {
"description": "Validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1SendersValidationErrorResponse"
},
"examples": {
"name_required": {
"summary": "Missing name",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"The field 'name' is required"
]
}
}
},
"email_required": {
"summary": "Missing email",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"Email is required"
]
}
}
},
"invalid_email": {
"summary": "Invalid email format",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"Email address is not valid"
]
}
}
},
"blocked_domain": {
"summary": "Free or personal email provider",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"Third party email providers such as gmail.com, yahoo.com, etc. cannot be used as senders"
]
}
}
},
"duplicate": {
"summary": "Duplicate name and email combination",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"A sender with this name and email already exists"
]
}
}
}
}
}
}
}
}
}
},
"/v1/senders/{id}": {
"get": {
"summary": "Get a single sender identity",
"description": "Returns a single sender identity by ID. Returns an empty array ([]) if the ID is not found.",
"operationId": "getSender",
"tags": [
"Senders"
],
"parameters": [
{
"$ref": "#/components/parameters/SenderId"
},
{
"$ref": "#/components/parameters/V1SendersFields"
}
],
"responses": {
"200": {
"description": "The requested sender identity, or an empty array if not found.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/Sender"
},
{
"type": "array",
"maxItems": 0
}
]
},
"examples": {
"found": {
"summary": "Sender found",
"value": {
"id": "1",
"name": "City of Harborview",
"email": "communications@harborview.gov",
"is_default": true
}
},
"not_found": {
"summary": "Sender not found",
"value": []
}
}
}
}
}
}
},
"patch": {
"summary": "Update a sender identity",
"description": "Updates the name and/or email of an existing sender identity. At least one field must be provided. id and is_default are read-only and cannot be changed via PATCH — to change the default sender use POST /senders/{id}/default. If id is included in the request body it must match the {id} in the URL.",
"operationId": "updateSender",
"tags": [
"Senders"
],
"parameters": [
{
"$ref": "#/components/parameters/SenderId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SenderUpdate"
},
"examples": {
"rename": {
"summary": "Update the name only",
"value": {
"name": "Office of Communications"
}
},
"update_email": {
"summary": "Update the email only",
"value": {
"email": "info@harborview.gov"
}
},
"both": {
"summary": "Update both name and email",
"value": {
"name": "Office of Communications",
"email": "info@harborview.gov"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Sender updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1SendersUpdateSuccessResponse"
},
"example": {
"success": true,
"result_text": "Updated",
"result_data": {
"id": "2",
"name": "Office of Communications",
"email": "info@harborview.gov",
"is_default": false,
"dkim_status": {
"verified": true,
"domain": "harborview.gov"
}
}
}
}
}
},
"400": {
"description": "Validation error, sender not found, or id mismatch.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/V1SendersValidationErrorResponse"
},
{
"$ref": "#/components/schemas/V1SendersErrorResponse"
}
]
},
"examples": {
"not_found": {
"summary": "Sender not found",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"errors": [
"Item with id '42' not found"
]
}
},
"id_mismatch": {
"summary": "id in body does not match URL id",
"value": {
"success": false,
"result_text": "Provided 'id': 2 does not match 'id' in request body (999)",
"result_data": []
}
},
"invalid_email": {
"summary": "Invalid email format",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"Email address is not valid"
]
}
}
}
}
}
}
}
}
},
"delete": {
"summary": "Delete a sender identity",
"description": "Permanently deletes a sender identity. The default sender cannot be deleted — use POST /senders/{id}/default to promote a different identity first.",
"operationId": "deleteSender",
"tags": [
"Senders"
],
"parameters": [
{
"$ref": "#/components/parameters/SenderId"
}
],
"responses": {
"200": {
"description": "Sender deleted successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1SendersDeleteSuccessResponse"
},
"example": {
"success": true,
"result_text": "Deleted",
"result_data": []
}
}
}
},
"400": {
"description": "Sender not found or sender is the default.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1SendersValidationErrorResponse"
},
"examples": {
"not_found": {
"summary": "Sender not found",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"errors": [
"Item with id '42' not found"
]
}
},
"is_default": {
"summary": "Cannot delete the default sender",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"The default sender identity cannot be deleted"
]
}
}
}
}
}
}
}
}
}
},
"/v1/senders/{id}/default": {
"post": {
"summary": "Set the default sender",
"description": "Promotes the specified sender identity to be the account's default. Clears the default flag from all other identities and syncs the account's default From name and email. The default sender is used automatically when no sender is explicitly specified in a campaign.",
"operationId": "setDefaultSender",
"tags": [
"Senders"
],
"parameters": [
{
"$ref": "#/components/parameters/SenderId"
}
],
"responses": {
"200": {
"description": "Default sender updated successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetDefaultSuccessResponse"
},
"example": {
"success": true,
"result_text": "Updated",
"result_data": []
}
}
}
},
"400": {
"$ref": "#/components/responses/V1SendersNotFoundMutate"
}
}
}
},
"/v2/reports/messages": {
"get": {
"tags": [
"Message activity"
],
"operationId": "listMessageActivity",
"summary": "List activity metrics per message",
"description": "One row per message with the ten metrics as integers, newest sent_time first then highest id (fixed order). Includes sent campaigns and automated messages; `type` narrows, `include_in_progress=1` adds campaigns still sending; drafts, scheduled, Transactional-status, and deleted or hidden messages never appear (an automated message whose sequence is transactional is included). A message is listed when it matches every filter, with zeros when it has no activity; with an activity window, messages launched after `activity_to` are left out. A/B tests are one row with `has_variants: true` and, for a subject-line test, `subject: null`. Filters combine with AND. Unknown parameters give `Parameter '{name}' is not valid`.",
"parameters": [
{
"name": "message_id",
"in": "query",
"description": "One message ID (`message_id=2001`) or several (`message_id[]=2001&message_id[]=2004`). Not a whole number: `Invalid 'message_id': '{value}'`.",
"schema": {
"oneOf": [
{
"type": "integer"
},
{
"type": "array",
"items": {
"type": "integer"
}
}
]
},
"example": 2001
},
{
"name": "group_id",
"in": "query",
"description": "One message folder ID or several (`group_id[]=`). Messages in the folder or in any of its subfolders, at any depth, are included (the beta's message_group_id took direct members only).",
"schema": {
"oneOf": [
{
"type": "integer"
},
{
"type": "array",
"items": {
"type": "integer"
}
}
]
},
"example": 31
},
{
"name": "tag_id",
"in": "query",
"description": "Only messages whose recipient_tag is this tag. Takes the tag's ID (from `GET /v2/tags`), not the name the row shows. One value (`Parameter 'tag_id' accepts one value`).",
"schema": {
"type": "integer"
},
"example": 512
},
{
"name": "segment_id",
"in": "query",
"description": "Only messages whose recipient_segment is this segment. Takes the segment's ID (from the segments in the Envoke app), not the name the row shows. One value.",
"schema": {
"type": "integer"
},
"example": 77
},
{
"name": "subscription_id",
"in": "query",
"description": "Only messages whose recipient_subscription is this subscription. Takes the subscription's ID (from `GET /v2/subscriptions`), not the name the row shows. One value.",
"schema": {
"type": "integer"
},
"example": 514
},
{
"name": "type",
"in": "query",
"description": "`campaign` or `automated`; both by default. Otherwise `Invalid 'type': '{value}' (possible values: 'campaign', 'automated')`.",
"schema": {
"type": "string",
"enum": [
"campaign",
"automated"
]
},
"example": "automated"
},
{
"name": "include_in_progress",
"in": "query",
"description": "`1` adds campaigns still sending (AB test in progress, Queuing, Sending); their numbers change until the send completes. Otherwise `Invalid 'include_in_progress': '{value}' (possible values: '0', '1')`.",
"schema": {
"type": "integer",
"enum": [
0,
1
],
"default": 0
},
"example": 1
},
{
"$ref": "#/components/parameters/SentFrom"
},
{
"$ref": "#/components/parameters/SentTo"
},
{
"$ref": "#/components/parameters/ActivityFrom"
},
{
"$ref": "#/components/parameters/ActivityTo"
},
{
"$ref": "#/components/parameters/V2ReportsLimit"
},
{
"$ref": "#/components/parameters/V2ReportsSkip"
}
],
"responses": {
"200": {
"description": "Rows, or `[]` when nothing matches.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageActivityRow"
}
},
"examples": {
"array": {
"summary": "One row",
"value": [
{
"id": "2001",
"name": "Spring Season Announcement",
"subject": "Our spring season is here, {fname}",
"type": "campaign",
"sent_time": "2026-04-15 10:00:00",
"recipient_subscription": "Season News",
"recipient_tag": "",
"recipient_segment": "",
"has_variants": false,
"sends": 412,
"delivered": 403,
"bounces": 9,
"hard_bounces": 5,
"soft_bounces": 4,
"opens": 188,
"clicks": 57,
"unsubscribes": 4,
"spam_complaints": 1,
"skips": 6
}
]
},
"empty": {
"summary": "Nothing matches",
"value": []
}
}
}
}
},
"400": {
"description": "Validation failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ReportsValidationErrorResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/V2ReportsUnauthorized"
},
"403": {
"$ref": "#/components/responses/V2ReportsForbidden"
},
"429": {
"$ref": "#/components/responses/V2ReportsTooManyRequests"
}
}
}
},
"/v2/reports/messages/{id}": {
"get": {
"tags": [
"Message stats"
],
"operationId": "getMessageStats",
"summary": "Get the full report for one message",
"description": "Totals, rates, bounce and preference-change breakdowns, links, email clients, unsubscribe reasons, polls and A/B variants for one message. Accepts only `activity_from` and `activity_to`; with either, `unsubscribe_reasons` and `polls` are `null` because they describe contacts as they are now. `variants` is always included when `has_variants` is true; no parameter requests or suppresses it. It is `[]` when the message's A/B block no longer exists. A message that does not exist, belongs to another account, is deleted, or has not started sending returns `[]`.",
"parameters": [
{
"$ref": "#/components/parameters/V2ReportsMessageId"
},
{
"$ref": "#/components/parameters/ActivityFrom"
},
{
"$ref": "#/components/parameters/ActivityTo"
}
],
"responses": {
"200": {
"description": "The report, or `[]`.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/MessageStats"
},
{
"$ref": "#/components/schemas/EmptyResult"
}
]
},
"examples": {
"report": {
"summary": "A message",
"value": {
"id": "2001",
"name": "Spring Season Announcement",
"subject": "Our spring season is here, {fname}",
"type": "campaign",
"sent_time": "2026-04-15 10:00:00",
"has_variants": false,
"totals": {
"sends": 412,
"delivered": 403,
"bounces": 9,
"hard_bounces": 5,
"soft_bounces": 4,
"opens": 188,
"clicks": 57,
"unsubscribes": 4,
"spam_complaints": 1,
"skips": 6
},
"rates": {
"delivered": 0.9782,
"open": 0.4665,
"click": 0.1414,
"click_to_open": 0.3032,
"bounce": 0.0218,
"unsubscribe": 0.0097
},
"bounces": [
{
"type": "hard_bounce",
"label": "Hard bounce",
"contacts": 3
},
{
"type": "soft_bounce",
"label": "Soft bounce",
"contacts": 2
},
{
"type": "deferred",
"label": "Temporarily deferred",
"contacts": 1
},
{
"type": "rejected",
"label": "Rejected",
"contacts": 0
},
{
"type": "invalid_address",
"label": "Invalid email address",
"contacts": 2
},
{
"type": "other",
"label": "Other",
"contacts": 1
}
],
"preference_changes": [
{
"type": "revoked_consent",
"label": "Revoked consent",
"contacts": 3
},
{
"type": "one_click_unsubscribe",
"label": "One-click unsubscribe",
"contacts": 2
},
{
"type": "spam_reported",
"label": "Spam reported",
"contacts": 1
},
{
"type": "subscription_changed",
"label": "Subscription changed",
"contacts": 2
},
{
"type": "language_changed",
"label": "Language changed",
"contacts": 1
},
{
"type": "express_consent_granted",
"label": "Express consent granted",
"contacts": 0
}
],
"links": [
{
"id": "88121",
"url": "https://example.org/season",
"title": "See the full season",
"type": "link",
"clicks": 41
},
{
"id": "88122",
"url": "https://example.org/tickets/season-pass",
"title": "Buy a season pass",
"type": "link",
"clicks": 22
},
{
"id": "88124",
"url": "",
"title": "Envoke Preferences / Unsubscribe",
"type": "pref",
"clicks": 6
},
{
"id": "88123",
"url": "",
"title": "Envoke View Message in Browser",
"type": "view",
"clicks": 4
}
],
"email_clients": {
"known_opens": 196,
"machine_open_records": 52,
"by_app": [
{
"name": "Apple Mail",
"opens": 74
},
{
"name": "Gmail",
"opens": 61
},
{
"name": "Outlook",
"opens": 38
},
{
"name": "Yahoo",
"opens": 6
},
{
"name": "Other",
"opens": 17
}
]
},
"unsubscribe_reasons": [
{
"reason": "no_longer_interested",
"contacts": 1
},
{
"reason": "too_many_emails",
"contacts": 2
}
],
"polls": [],
"variants": []
}
},
"empty": {
"summary": "Not found",
"value": []
}
}
}
}
},
"400": {
"description": "Validation failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ReportsValidationErrorResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/V2ReportsUnauthorized"
},
"403": {
"$ref": "#/components/responses/V2ReportsForbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/V2ReportsTooManyRequests"
}
}
}
},
"/v2/reports/messages/compare": {
"get": {
"tags": [
"Message stats"
],
"operationId": "compareMessageStats",
"summary": "Compare several messages or a folder",
"description": "Totals and rates per message plus a combined block whose totals are distinct contacts across the set. Give exactly one of `message_id` (one or more, at most 100; a repeated ID counts once) or `group_id` (one folder, subfolders included). With an activity window, messages launched after `activity_to` are left out of the set, as the list leaves them out; a `message_id` launched later is dropped without an error. Errors: `One of the parameters 'message_id' or 'group_id' must be provided`, `Only one of the parameters 'message_id' or 'group_id' may be provided`, `No message found for 'message_id': {id}` (one per unknown id, including messages in other accounts, deleted, or not sent), `No message group found for 'group_id': {id}`, `Too many messages to compare: {n} (maximum 100)`.",
"parameters": [
{
"name": "message_id",
"in": "query",
"description": "One or more message IDs (`message_id[]=2001&message_id[]=2004`), each a sent campaign or automated message in the account. At most 100; a repeated ID counts once.",
"schema": {
"oneOf": [
{
"type": "integer"
},
{
"type": "array",
"items": {
"type": "integer"
},
"maxItems": 100
}
]
},
"example": [
2001,
2004
]
},
{
"name": "group_id",
"in": "query",
"description": "One message folder ID; every sent campaign and automated message filed in it or in any of its subfolders, at any depth.",
"schema": {
"type": "integer"
},
"example": 31
},
{
"$ref": "#/components/parameters/ActivityFrom"
},
{
"$ref": "#/components/parameters/ActivityTo"
}
],
"responses": {
"200": {
"description": "The comparison.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompareResponse"
},
"examples": {
"two": {
"summary": "Two messages",
"value": {
"messages": [
{
"id": "2004",
"name": "Pirates Opening Night",
"sent_time": "2026-05-14 09:30:00",
"totals": {
"sends": 386,
"delivered": 379,
"bounces": 7,
"hard_bounces": 4,
"soft_bounces": 3,
"opens": 201,
"clicks": 64,
"unsubscribes": 2,
"spam_complaints": 0,
"skips": 3
},
"rates": {
"delivered": 0.9819,
"open": 0.5303,
"click": 0.1689,
"click_to_open": 0.3184,
"bounce": 0.0181,
"unsubscribe": 0.0052
}
},
{
"id": "2001",
"name": "Spring Season Announcement",
"sent_time": "2026-04-15 10:00:00",
"totals": {
"sends": 412,
"delivered": 403,
"bounces": 9,
"hard_bounces": 5,
"soft_bounces": 4,
"opens": 188,
"clicks": 57,
"unsubscribes": 4,
"spam_complaints": 1,
"skips": 6
},
"rates": {
"delivered": 0.9782,
"open": 0.4665,
"click": 0.1414,
"click_to_open": 0.3032,
"bounce": 0.0218,
"unsubscribe": 0.0097
}
}
],
"combined": {
"message_count": 2,
"totals": {
"sends": 702,
"delivered": 686,
"bounces": 16,
"hard_bounces": 9,
"soft_bounces": 7,
"opens": 331,
"clicks": 108,
"unsubscribes": 6,
"spam_complaints": 1,
"skips": 9
},
"rates": {
"delivered": 0.9772,
"open": 0.4825,
"click": 0.1574,
"click_to_open": 0.3263,
"bounce": 0.0228,
"unsubscribe": 0.0085
}
}
}
}
}
}
}
},
"400": {
"description": "Validation failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ReportsValidationErrorResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/V2ReportsUnauthorized"
},
"403": {
"$ref": "#/components/responses/V2ReportsForbidden"
},
"429": {
"$ref": "#/components/responses/V2ReportsTooManyRequests"
}
}
}
},
"/v2/reports/messages/{id}/contacts": {
"get": {
"tags": [
"Message contacts"
],
"operationId": "listMessageContacts",
"summary": "List the contacts behind one message's metric",
"description": "One row per distinct contact with the event for the message: id, email, remote_id, event_time, count. Each event lists the contacts its metric counts, so the rows equal the single-message report's totals for the same window, less contacts deleted since; a message with an anonymous poll leaves every poll-answer click out of clicked. not_opened and not_clicked are the sent contacts minus the opened or clicked contacts, bounced contacts included (event_time null). Ordered by event_time descending then contact id descending (negative events by id descending). Answers for the same messages as the single-message report; a message that is not found returns []. Flat parameters, each taking one value except bounce_type, which accepts an array; any other parameter is a 400 `Parameter '{name}' is not valid`. On an account restricted from contact-level email activity, returns 403 for every event before checking parameters.",
"parameters": [
{
"$ref": "#/components/parameters/V2ReportsMessageId"
},
{
"$ref": "#/components/parameters/Event"
},
{
"$ref": "#/components/parameters/LinkId"
},
{
"$ref": "#/components/parameters/BounceType"
},
{
"$ref": "#/components/parameters/ActivityFrom"
},
{
"$ref": "#/components/parameters/ActivityTo"
},
{
"$ref": "#/components/parameters/ContactFields"
},
{
"$ref": "#/components/parameters/ContactsLimit"
},
{
"$ref": "#/components/parameters/V2ReportsSkip"
}
],
"responses": {
"200": {
"description": "The rows, or `[]`.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageContactRow"
}
},
"examples": {
"opened": {
"summary": "event=opened",
"value": [
{
"id": "1008",
"email": "p.nguyen@example.org",
"remote_id": "MRCT-0501",
"event_time": "2026-05-16 19:44:02",
"count": 2
},
{
"id": "1005",
"email": "l.ferreira@example.org",
"remote_id": "",
"event_time": "2026-05-15 07:12:55",
"count": 1
},
{
"id": "1004",
"email": "maya.chen@example.org",
"remote_id": "MRCT-0412",
"event_time": "2026-05-14 12:02:44",
"count": 1
}
]
},
"ids": {
"summary": "event=not_opened&fields=id (sent, did not open)",
"value": [
{
"id": "1006"
},
{
"id": "1003"
},
{
"id": "1002"
}
]
},
"empty": {
"summary": "Not found, or no contact has the event",
"value": []
}
}
}
}
},
"400": {
"description": "Validation failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ReportsValidationErrorResponse"
},
"example": {
"success": false,
"result_data": {
"errors": [
"Parameter 'event' must be provided",
"Invalid 'activity_from': '05/14/2026' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)"
]
},
"result_text": "Validation failed, see 'result_data' -> 'errors'"
}
}
}
},
"401": {
"$ref": "#/components/responses/V2ReportsUnauthorized"
},
"403": {
"$ref": "#/components/responses/ContactForbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/V2ReportsTooManyRequests"
}
}
}
},
"/v2/reports/contacts/{id}": {
"get": {
"tags": [
"Contact activity"
],
"operationId": "getContactActivity",
"summary": "Get one contact's email activity",
"description": "The contact, a summary of message counts, and the messages the contact was sent (newest first, paged with limit and skip; summary is never paged). A contact that does not exist, belongs to another account, or is deleted returns `[]`. On an account restricted from contact-level email activity, returns 403 `Contact-level email activity is not available on this account`.",
"parameters": [
{
"$ref": "#/components/parameters/V2ReportsContactId"
},
{
"$ref": "#/components/parameters/ActivityFrom"
},
{
"$ref": "#/components/parameters/ActivityTo"
},
{
"$ref": "#/components/parameters/V2ReportsLimit"
},
{
"$ref": "#/components/parameters/V2ReportsSkip"
}
],
"responses": {
"200": {
"description": "The activity, or `[]`.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ContactActivity"
},
{
"$ref": "#/components/schemas/EmptyResult"
}
]
},
"examples": {
"activity": {
"summary": "A contact",
"value": {
"contact": {
"id": "1004",
"email": "maya.chen@example.org",
"remote_id": "MRCT-0412"
},
"summary": {
"sends": 3,
"delivered": 3,
"bounces": 0,
"opens": 2,
"clicks": 1,
"unsubscribes": 0,
"last_send_time": "2026-05-14 09:31:07",
"last_open_time": "2026-05-14 12:02:44",
"last_click_time": "2026-05-14 12:03:10"
},
"messages": [
{
"id": "2004",
"name": "Pirates Opening Night",
"sent_time": "2026-05-14 09:31:07",
"delivered": true,
"bounced": false,
"opened": true,
"first_open_time": "2026-05-14 12:02:44",
"opens": 1,
"clicked": true,
"clicks": 1,
"links": [
{
"id": "88125",
"url": "https://example.org/tickets/pirates",
"first_click_time": "2026-05-14 12:03:10"
}
],
"unsubscribed": false
}
]
}
},
"empty": {
"summary": "Not found",
"value": []
}
}
}
}
},
"400": {
"description": "Validation failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ReportsValidationErrorResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/V2ReportsUnauthorized"
},
"403": {
"$ref": "#/components/responses/ContactForbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/V2ReportsTooManyRequests"
}
}
}
},
"/v2/reports/contacts": {
"get": {
"tags": [
"Contact activity"
],
"operationId": "findContactActivity",
"summary": "Find a contact's email activity by email or remote ID",
"description": "The same object as getContactActivity for the contact found by exactly one of `email` or `remote_id` (the whole value, compared as the Contact API's `filter[email]` and `filter[remote_id]` compare it; letter case does not matter). No match returns `[]`. Errors: `One of the parameters 'email' or 'remote_id' must be provided`, `Only one of the parameters 'email' or 'remote_id' may be provided`, `Invalid 'email': ''` (an empty value; also for `remote_id`), `More than one contact found for 'remote_id': '{value}'` (or `'email'`). On an account restricted from contact-level email activity, returns 403 `Contact-level email activity is not available on this account`.",
"parameters": [
{
"name": "email",
"in": "query",
"description": "The contact's email address, URL-encoded. Not with remote_id.",
"schema": {
"type": "string"
},
"example": "maya.chen@example.org"
},
{
"name": "remote_id",
"in": "query",
"description": "The contact's remote ID. Not with email. More than one matching contact is a 400.",
"schema": {
"type": "string"
},
"example": "MRCT-0412"
},
{
"$ref": "#/components/parameters/ActivityFrom"
},
{
"$ref": "#/components/parameters/ActivityTo"
},
{
"$ref": "#/components/parameters/V2ReportsLimit"
},
{
"$ref": "#/components/parameters/V2ReportsSkip"
}
],
"responses": {
"200": {
"description": "The activity, or `[]`.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ContactActivity"
},
{
"$ref": "#/components/schemas/EmptyResult"
}
]
},
"examples": {
"activity": {
"summary": "Found by remote_id",
"value": {
"contact": {
"id": "1004",
"email": "maya.chen@example.org",
"remote_id": "MRCT-0412"
},
"summary": {
"sends": 3,
"delivered": 3,
"bounces": 0,
"opens": 2,
"clicks": 1,
"unsubscribes": 0,
"last_send_time": "2026-05-14 09:31:07",
"last_open_time": "2026-05-14 12:02:44",
"last_click_time": "2026-05-14 12:03:10"
},
"messages": [
{
"id": "2004",
"name": "Pirates Opening Night",
"sent_time": "2026-05-14 09:31:07",
"delivered": true,
"bounced": false,
"opened": true,
"first_open_time": "2026-05-14 12:02:44",
"opens": 1,
"clicked": true,
"clicks": 1,
"links": [
{
"id": "88125",
"url": "https://example.org/tickets/pirates",
"first_click_time": "2026-05-14 12:03:10"
}
],
"unsubscribed": false
}
]
}
},
"empty": {
"summary": "No match",
"value": []
}
}
}
}
},
"400": {
"description": "Validation failed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2ReportsValidationErrorResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/V2ReportsUnauthorized"
},
"403": {
"$ref": "#/components/responses/ContactForbidden"
},
"429": {
"$ref": "#/components/responses/V2ReportsTooManyRequests"
}
}
}
},
"/v1/hooks.json": {
"get": {
"summary": "List webhook subscriptions",
"description": "Returns all webhook subscriptions for the authenticated account. All subscriptions are returned by default (no limit). Supports filtering by `type`, pagination, and field selection.",
"operationId": "listHooks",
"tags": [
"Hooks"
],
"parameters": [
{
"$ref": "#/components/parameters/V1HooksLimit"
},
{
"$ref": "#/components/parameters/V1HooksSkip"
},
{
"$ref": "#/components/parameters/V1HooksFields"
},
{
"$ref": "#/components/parameters/TypeFilter"
}
],
"responses": {
"200": {
"description": "An array of webhook subscriptions. Returns `[]` if none exist.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Hook"
}
},
"examples": {
"list": {
"summary": "Two subscriptions",
"value": [
{
"id": "9f1c2a42baedb56c7e65b3eeaf1a8814",
"type": "form_submission",
"url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
"filter": {
"form_id": "abc123def456"
}
},
{
"id": "a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7",
"type": "email_open",
"url": "https://hooks.zapier.com/hooks/catch/123456/ghijkl/",
"filter": {
"message_id": "789"
}
}
]
},
"filtered_by_type": {
"summary": "Filtered by type=form_submission",
"value": [
{
"id": "9f1c2a42baedb56c7e65b3eeaf1a8814",
"type": "form_submission",
"url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
"filter": {
"form_id": "abc123def456"
}
}
]
},
"empty": {
"summary": "No subscriptions",
"value": []
}
}
}
}
}
}
},
"post": {
"summary": "Create a webhook subscription",
"description": "Creates a new webhook subscription. `type` and `url` are required. `filter` is optional — omit it or pass `{}` to receive all events of the given type.\n\nReturns HTTP 201 on success. Returns HTTP 400 with a duplicate error if a subscription with the same `type` and `url` already exists.",
"operationId": "createHook",
"tags": [
"Hooks"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HookCreate"
},
"examples": {
"form_submission_with_filter": {
"summary": "Form submission — specific form (college admissions inquiry)",
"value": {
"type": "form_submission",
"url": "https://crm.ridgeline.edu/webhooks/envoke/admissions",
"filter": {
"form_id": "abc123def456"
}
}
},
"email_open_with_filter": {
"summary": "Email open — specific message by ID (fall registration reminder)",
"value": {
"type": "email_open",
"url": "https://portal.ridgeline.edu/webhooks/engagement",
"filter": {
"message_id": "789"
}
}
},
"email_click_with_filter": {
"summary": "Email click — specific message by external ID (alumni giving appeal)",
"value": {
"type": "email_click",
"url": "https://giving.ridgeline.edu/webhooks/envoke",
"filter": {
"message_external_id": "f5a3c1e9b7d5f3a1c9e7b5d3f1a9c7e5"
}
}
},
"email_bounce_hard_only": {
"summary": "Email bounce — hard bounces only (CRM address hygiene)",
"value": {
"type": "email_bounce",
"url": "https://crm.ridgeline.edu/webhooks/envoke/bounces",
"filter": {
"bounce_type": "hard"
}
}
},
"email_spam_report_no_filter": {
"summary": "Email spam report — all reports",
"value": {
"type": "email_spam_report",
"url": "https://crm.ridgeline.edu/webhooks/envoke/complaints",
"filter": {}
}
},
"new_contact_no_filter": {
"summary": "New contact — all new contacts (sync to student info system)",
"value": {
"type": "new_contact",
"url": "https://sis.ridgeline.edu/webhooks/contacts",
"filter": {}
}
},
"new_lead_no_filter": {
"summary": "New lead — all new leads (alert recruitment team)",
"value": {
"type": "new_lead",
"url": "https://crm.ridgeline.edu/webhooks/leads"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Subscription created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1HooksCreateSuccessResponse"
},
"example": {
"id": "9f1c2a42baedb56c7e65b3eeaf1a8814"
}
}
}
},
"400": {
"description": "Validation error or duplicate subscription.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/V1HooksValidationErrorResponse"
},
{
"$ref": "#/components/schemas/DuplicateErrorResponse"
}
]
},
"examples": {
"missing_type": {
"summary": "Missing required field: type",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"'type' is required"
]
}
}
},
"invalid_type": {
"summary": "Unrecognised event type",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"Invalid webhook type: 'contact_created'"
]
}
}
},
"missing_url": {
"summary": "Missing required field: url",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"'url' is required"
]
}
}
},
"invalid_url": {
"summary": "URL does not start with http:// or https://",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"'url' must start with http:// or https://"
]
}
}
},
"invalid_filter": {
"summary": "Filter value is not a scalar",
"value": {
"success": false,
"result_text": "Validation failed, see 'result_data' -> 'errors'",
"result_data": {
"errors": [
"'filter' values must be scalar (string, number, or boolean)"
]
}
}
},
"duplicate": {
"summary": "Duplicate subscription",
"value": {
"success": false,
"result_text": "A webhook subscription with this type and URL already exists",
"result_data": {
"id": "9f1c2a42baedb56c7e65b3eeaf1a8814"
}
}
}
}
}
}
}
}
}
},
"/v1/hooks/{id}.json": {
"get": {
"summary": "Get a single webhook subscription",
"description": "Returns a single webhook subscription by its ID. Returns `null` if the ID is not found.",
"operationId": "getHook",
"tags": [
"Hooks"
],
"parameters": [
{
"$ref": "#/components/parameters/HookId"
}
],
"responses": {
"200": {
"description": "The webhook subscription, or `null` if not found.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/Hook"
},
{
"type": "null"
}
]
},
"examples": {
"found": {
"summary": "Subscription found",
"value": {
"id": "9f1c2a42baedb56c7e65b3eeaf1a8814",
"type": "form_submission",
"url": "https://crm.ridgeline.edu/webhooks/envoke/admissions",
"filter": {
"form_id": "abc123def456"
}
}
},
"not_found": {
"summary": "Subscription not found",
"value": null
}
}
}
}
}
}
},
"delete": {
"summary": "Delete a webhook subscription",
"description": "Permanently deletes a webhook subscription. No further events are delivered once deleted. The operation is idempotent — deleting a non-existent ID returns a success response.",
"operationId": "deleteHook",
"tags": [
"Hooks"
],
"parameters": [
{
"$ref": "#/components/parameters/HookId"
}
],
"responses": {
"200": {
"description": "Subscription deleted (or did not exist — deletion is idempotent).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V1HooksDeleteSuccessResponse"
},
"example": {
"success": true,
"result_text": "Deleted",
"result_data": []
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic",
"description": "HTTP Basic Auth. Use your API ID as the username and API Key as the password. See https://developers.envoke.com/guides/authentication/."
}
},
"parameters": {
"V1ContactsContactId": {
"name": "id",
"in": "path",
"required": true,
"description": "The Envoke contact ID.",
"schema": {
"type": "integer",
"minimum": 1
},
"example": 1001
},
"V1ContactsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of contacts to return. Default 10, hard cap 100. When `fields` or `result_type=kvp` is also set, the default becomes 10,000 and a value above 100 is honoured as-is. `limit=1` returns a single contact as a bare object instead of an array (or `[]` when nothing matches). A value that is not a whole number gives `Invalid 'limit': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V1ContactsSkip": {
"name": "skip",
"in": "query",
"description": "Number of contacts to skip. Use with `limit` and `sort` to paginate. A value that is not a whole number gives `Invalid 'skip': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V1ContactsFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each result, e.g. `id,email`. On the list endpoint, setting it raises the default limit to 10,000 and lifts the 100 cap.",
"schema": {
"type": "string"
},
"example": "id,email,consent_status"
},
"V1ContactsResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive an object of contact ID to email address (`{ \"1001\": \"alto.lead@example.com\" }`) instead of an array. Raises the default limit to 10,000 and lifts the 100 cap. Has no effect when `limit=1`.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"KeyFieldCreate": {
"name": "key_field",
"in": "query",
"description": "The field used to check whether the contact already exists: `email` (default) or `remote_id`. With `remote_id`, the body must include `remote_id`. Any other value gives `Invalid 'key_field' value: '{value}'`. The parameter is `key_field`; the misspelling `keyfield` is ignored without an error.",
"schema": {
"type": "string",
"enum": [
"email",
"remote_id"
],
"default": "email"
}
},
"KeyFieldUpdate": {
"name": "key_field",
"in": "query",
"description": "How `PATCH /contacts` with an object body finds the contact: `id` (looked up), `email`, or `remote_id`. When not set, a body `id` is used directly without a lookup, otherwise `email`. Ignored for list bodies and by `PATCH /contacts/{id}`. Any other value gives `Invalid 'key_field' value: '{value}'`.",
"schema": {
"type": "string",
"enum": [
"id",
"email",
"remote_id"
]
}
},
"Upsert": {
"name": "upsert",
"in": "query",
"description": "When `1`, `true`, `yes`, or `on`, an existing contact matched by `key_field` is updated instead of rejected as a duplicate. An empty value (`?upsert=`) is false. An upsert that updates ignores empty values (`write_empty_values` has no effect on POST, though a custom field value of `\"\"` still deletes that value), does not default `consent_status` to `Not Provided`, ignores `id` in the body, and appends warnings after `. `, giving a double period.",
"schema": {
"type": "boolean",
"default": false
}
},
"WriteEmptyValues": {
"name": "write_empty_values",
"in": "query",
"description": "When `1`, `true`, `yes`, or `on`, an empty string (`\"\"`) clears a text field. Otherwise `\"\"`, `0`, `\"0\"`, `false`, and `[]` are ignored; `null` is always ignored. A custom field value of `\"\"` deletes that value with or without this parameter. `email` cannot be cleared (`Email must not be empty`), and `country` and `language` cannot be cleared.",
"schema": {
"type": "boolean",
"default": false
}
},
"TagId": {
"name": "id",
"in": "path",
"required": true,
"description": "The unique ID of the tag.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V2TagsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of records to return. Default is 10, hard cap is 100. When used alongside `?fields=` or `?result_type=kvp`, the cap is lifted and an explicit limit above 100 is honoured as-is.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V2TagsSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V2TagsFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object. When set, the default limit increases to 10,000 and the 100-record hard cap is lifted.",
"schema": {
"type": "string"
},
"example": "id,name,group"
},
"V2TagsResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive results as a flat key-value object (`{ \"\": \"\" }`) instead of an array of objects. When set, the default limit increases to 10,000 and the hard cap is lifted.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"SubscriptionId": {
"name": "id",
"in": "path",
"required": true,
"description": "The unique ID of the subscription.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V2SubscriptionsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of records to return. Default is 10, hard cap is 100. When used alongside `?fields=` or `?result_type=kvp`, the cap is lifted and an explicit limit above 100 is honoured as-is.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V2SubscriptionsSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V2SubscriptionsFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object. When set, the default limit increases to 10,000 and the 100-record hard cap is lifted.",
"schema": {
"type": "string"
},
"example": "id,name,group"
},
"V2SubscriptionsResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive results as a flat key-value object (`{ \"\": \"\" }`) instead of an array of objects. When set, the default limit increases to 10,000 and the hard cap is lifted.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"CustomFieldId": {
"name": "id",
"in": "path",
"required": true,
"description": "The unique ID of the custom field.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V2CustomfieldsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of records to return. Default is 10, hard cap is 100. When used alongside `?fields=` or `?result_type=kvp` (shaped responses), the cap is lifted and an explicit limit above 100 is honoured as-is.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V2CustomfieldsSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V2CustomfieldsFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object. When omitted, all fields are returned. When set, the default limit increases to 10,000 and the 100-record hard cap is lifted.",
"schema": {
"type": "string"
},
"example": "id,name,field_type"
},
"V2CustomfieldsResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive results as a flat key-value object (`{ \"\": \"\" }`) instead of an array of objects. Useful for populating dropdowns. When set, the default limit increases to 10,000 and the 100-record hard cap is lifted.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"GroupType": {
"name": "type",
"in": "path",
"required": true,
"description": "The item type whose groups are being managed.",
"schema": {
"type": "string",
"enum": [
"tags",
"subscriptions",
"messages",
"templates"
]
}
},
"GroupId": {
"name": "id",
"in": "path",
"required": true,
"description": "The unique ID of the group.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V2GroupsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of records to return. Default is 10, hard cap is 100. When used alongside `?fields=` or `?result_type=kvp`, the cap is lifted and an explicit limit above 100 is honoured as-is.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V2GroupsSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V2GroupsFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object. When set, the default limit increases to 10,000 and the 100-record hard cap is lifted.",
"schema": {
"type": "string"
},
"example": "id,name"
},
"V2GroupsResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive results as a flat key-value object (`{ \"\": \"\" }`) instead of an array of objects. When set, the default limit increases to 10,000 and the hard cap is lifted.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"TemplateId": {
"name": "id",
"in": "path",
"required": true,
"description": "The unique ID of the template.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V2TemplatesLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of records to return. Default is 10, hard cap is 100. When used alongside `?fields=` or `?result_type=kvp`, the cap is lifted and an explicit limit above 100 is honoured as-is.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V2TemplatesSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V2TemplatesFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object. When set, the default limit increases to 10,000 and the 100-record hard cap is lifted.",
"schema": {
"type": "string"
},
"example": "id,name,status"
},
"V2TemplatesResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive results as a flat key-value object (`{ \"\": \"\" }`) instead of an array of objects. When set, the default limit increases to 10,000 and the hard cap is lifted.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"IncludeHTML": {
"name": "include_html",
"in": "query",
"description": "Set to `1` to include the full HTML content in a single-template response. Has no effect on list requests.",
"schema": {
"type": "integer",
"enum": [
0,
1
],
"default": 0
}
},
"V2MessagesMessageId": {
"name": "id",
"in": "path",
"required": true,
"description": "The Envoke message ID.",
"schema": {
"type": "integer",
"minimum": 1
},
"example": 2001
},
"V2MessagesLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of messages to return. Default 10, hard cap 100. When `fields` or `result_type=kvp` is also set, the default becomes 10,000 and a value above 100 is honoured as-is. `limit=1` returns a single message as a bare object instead of an array (or `[]` when nothing matches), and `result_type=kvp` has no effect with it. A value that is not a whole number gives `Invalid 'limit': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V2MessagesSkip": {
"name": "skip",
"in": "query",
"description": "Number of messages to skip. Use with `limit` and `sort` to paginate. A value that is not a whole number gives `Invalid 'skip': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V2MessagesFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each result, e.g. `id,name,status`. Use names from the Message schema. On the list endpoint, setting it raises the default limit to 10,000 and lifts the 100 cap. On a single GET with `include_html`, list `html` to keep the HTML.",
"schema": {
"type": "string"
},
"example": "id,name,status,send_time"
},
"V2MessagesResultType": {
"name": "result_type",
"in": "query",
"description": "Set to `kvp` to receive an object of message ID to name (`{ \"2001\": \"Spring Season Announcement\" }`) instead of an array. Raises the default limit to 10,000 and lifts the 100 cap. Has no effect when `limit=1` or on a single GET.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"IncludeHtml": {
"name": "include_html",
"in": "query",
"description": "Single GET only. `1` adds the message HTML as the last key, `html`. With `0` or without the parameter, the HTML is left out. When `fields` is also set, list `html` in it to keep the HTML. Ignored on the list endpoint, which never returns HTML.",
"schema": {
"type": "integer",
"enum": [
0,
1
]
},
"example": 1
},
"SenderId": {
"name": "id",
"in": "path",
"required": true,
"description": "The unique ID of the sender identity.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V1SendersLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of records to return. Default is 10, hard cap is 100. When used alongside ?fields= or ?result_type=kvp, the cap is lifted and an explicit limit above 100 is honoured as-is.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 10
}
},
"V1SendersSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V1SendersFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object. When set, the default limit increases to 10,000 and the hard cap is lifted.",
"schema": {
"type": "string"
},
"example": "id,name,email"
},
"V1SendersResultType": {
"name": "result_type",
"in": "query",
"description": "Set to kvp to receive results as a flat key-value object ({ \"\": \"\" }) instead of an array of objects. When set, the default limit increases to 10,000 and the hard cap is lifted.",
"schema": {
"type": "string",
"enum": [
"kvp"
]
}
},
"SentFrom": {
"name": "sent_from",
"in": "query",
"description": "Only messages whose sent_time is on or after this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'sent_from': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.",
"schema": {
"type": "string"
},
"example": "2026-04-01"
},
"SentTo": {
"name": "sent_to",
"in": "query",
"description": "Only messages whose sent_time is on or before this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'sent_to': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.",
"schema": {
"type": "string"
},
"example": "2026-04-30"
},
"ActivityFrom": {
"name": "activity_from",
"in": "query",
"description": "Count only activity records made on or after this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'activity_from': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.",
"schema": {
"type": "string"
},
"example": "2026-05-01"
},
"ActivityTo": {
"name": "activity_to",
"in": "query",
"description": "Count only activity records made on or before this value. `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS` (URL-encode the space), read in the account's time zone (the zone the Message API uses); inclusive; a date alone covers the whole day; the year must be from 1970 to 2999. Any other value gives `Invalid 'activity_to': '{value}' (expected YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)`.",
"schema": {
"type": "string"
},
"example": "2026-05-31 23:59:59"
},
"V2ReportsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of items. Default 10, hard cap 100 (larger values return 100); `0`, a value of zeros such as `00`, or empty gives the default; `limit=1` still returns an array. Not a whole number: `Invalid 'limit': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 10
},
"example": 25
},
"V2ReportsSkip": {
"name": "skip",
"in": "query",
"description": "Number of items to skip. Not a whole number: `Invalid 'skip': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"example": 25
},
"V2ReportsMessageId": {
"name": "id",
"in": "path",
"required": true,
"description": "The Envoke message ID. A non-numeric value returns 404.",
"schema": {
"type": "integer",
"minimum": 1
},
"example": 2004
},
"V2ReportsContactId": {
"name": "id",
"in": "path",
"required": true,
"description": "The Envoke contact ID (Contact API `id`). A non-numeric value returns 404.",
"schema": {
"type": "integer",
"minimum": 1
},
"example": 1004
},
"Event": {
"name": "event",
"in": "query",
"required": true,
"description": "Which contacts to list. sent: type 1 (rows = totals.sends). delivered: sent with no bounce record for the message; in an activity window, sent inside the window with no bounce at any time (rows = totals.delivered). bounced: any type 2, or the bounce_type reasons (rows = totals.bounces). opened: type 3 (rows = totals.opens). clicked: type 4, or the link_id link (rows = totals.clicks, except that a message with an anonymous poll leaves out every poll-answer click). unsubscribed: 5/11 or 5/30 (rows = totals.unsubscribes). spam_reported: 5/12 or 5/13 (rows = totals.spam_complaints). skipped: type 6 (rows = totals.skips). not_opened and not_clicked: the sent contacts minus the opened (or clicked) contacts, bounced contacts included, as the segment conditions \"didn't open\" and \"didn't click\" (lifetime, not_opened is sent minus the sent contacts who opened; Envoke can record an open or click for a contact with no send record, who is in opened but not in sent or not_opened, so not_opened + opened can exceed sent). Contacts deleted since are not listed. Missing: `Parameter 'event' must be provided`; other values: `Invalid 'event': '{value}' (possible values: 'sent', 'delivered', 'bounced', 'opened', 'clicked', 'unsubscribed', 'spam_reported', 'skipped', 'not_opened', 'not_clicked')`.",
"schema": {
"type": "string",
"enum": [
"sent",
"delivered",
"bounced",
"opened",
"clicked",
"unsubscribed",
"spam_reported",
"skipped",
"not_opened",
"not_clicked"
]
},
"example": "opened"
},
"LinkId": {
"name": "link_id",
"in": "query",
"description": "With event=clicked, only contacts who clicked this link; with event=not_clicked, sent contacts who did not click it. One tracked link of the message (the id in the single-message report's links); poll answers are not accepted. Not a whole number: `Invalid 'link_id': '{value}'`; not a link of this message: `Invalid 'link_id': '{value}'` (checked only when the message is found); with another event: `Parameter 'link_id' requires event 'clicked' or 'not_clicked'`.",
"schema": {
"type": "integer",
"minimum": 1
},
"example": 88125
},
"BounceType": {
"name": "bounce_type",
"in": "query",
"description": "With event=bounced, only contacts with one of these bounce reasons, the type keys of the single-message report's bounces block. One value or several (`bounce_type[]=hard_bounce&bounce_type[]=invalid_address` lists the contacts of hard_bounces). Other values: `Invalid 'bounce_type': '{value}' (possible values: 'hard_bounce', 'soft_bounce', 'deferred', 'rejected', 'invalid_address', 'other')`; with another event: `Parameter 'bounce_type' requires event 'bounced'`.",
"schema": {
"oneOf": [
{
"type": "string",
"enum": [
"hard_bounce",
"soft_bounce",
"deferred",
"rejected",
"invalid_address",
"other"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"hard_bounce",
"soft_bounce",
"deferred",
"rejected",
"invalid_address",
"other"
]
}
}
]
},
"example": "hard_bounce"
},
"ContactFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated row fields to return, from id, email, remote_id, event_time and count; returned in that order whatever the order given. Lifts the limit: with fields and no limit, up to 10,000 rows; a limit above 100 is honoured up to 10,000, larger values return 10,000. Applies to every event. Other names, or an empty value: `Invalid 'fields': '{name}' (possible values: 'id', 'email', 'remote_id', 'event_time', 'count')`.",
"schema": {
"type": "string"
},
"example": "id,email"
},
"ContactsLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of rows. Default 10, cap 100 (larger values return 100); with fields, default 10,000 and cap 10,000. `0` or empty gives the default (10,000 with fields); a value of several zeros such as `00` gives 10, with or without fields; `limit=1` still returns an array. Not a whole number: `Invalid 'limit': '{value}'`.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 10
},
"example": 100
},
"HookId": {
"name": "id",
"in": "path",
"required": true,
"description": "The 32-character hex ID of the webhook subscription.",
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{32}$"
}
},
"V1HooksLimit": {
"name": "limit",
"in": "query",
"description": "Maximum number of subscriptions to return. When omitted, all subscriptions are returned.",
"schema": {
"type": "integer",
"minimum": 1
}
},
"V1HooksSkip": {
"name": "skip",
"in": "query",
"description": "Number of records to skip. Used with `limit` for pagination.",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"V1HooksFields": {
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in each response object.",
"schema": {
"type": "string"
},
"example": "id,type,url"
},
"TypeFilter": {
"name": "type",
"in": "query",
"description": "Filter results to subscriptions matching the given event type.",
"schema": {
"$ref": "#/components/schemas/HookType"
}
}
},
"schemas": {
"Contact": {
"type": "object",
"description": "A contact as returned by GET and by the create, upsert, and key-field update responses. Every field is present unless `fields` selects some. An unset value is `\"\"`, never `null` (a stored `\"0\"` is also returned as `\"\"`).",
"required": [
"id",
"external_id",
"date_created",
"remote_id",
"first_name",
"last_name",
"title",
"email",
"company",
"phone",
"address_1",
"address_2",
"city",
"country",
"province",
"postal_code",
"website",
"language",
"feedback",
"consent_status",
"consent_description",
"consent_effective_date",
"consent_expiry",
"custom_fields",
"interests",
"autoresponders"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Envoke contact ID, assigned on creation. Returned as a string.",
"examples": [
"1001"
]
},
"external_id": {
"type": "string",
"readOnly": true,
"description": "32-character identifier used in public-facing links such as preference pages. Not the same as `id`. Ignored on write.",
"examples": [
"9f2c4e7a1b3d5f6a8c0e2b4d6f8a1c3e"
]
},
"date_created": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "When the contact was created, W3C format in UTC. Ignored on write. Filterable with the range operators.",
"examples": [
"2026-10-05T14:03:11+00:00"
]
},
"remote_id": {
"type": "string",
"maxLength": 60,
"description": "Your own identifier for the contact, e.g. a CRM or membership ID. Usable as the key field on create and update. Too long: `Remote ID must not exceed 60 characters`.",
"examples": [
"HCS-0002",
""
]
},
"first_name": {
"type": "string",
"maxLength": 50,
"description": "First name. Too long: `First name must not exceed 50 characters`.",
"examples": [
"Maya"
]
},
"last_name": {
"type": "string",
"maxLength": 50,
"description": "Last name. Too long: `Last name must not exceed 50 characters`.",
"examples": [
"Okafor"
]
},
"title": {
"type": "string",
"maxLength": 50,
"description": "Job title or honorific. Too long: `Title must not exceed 50 characters`.",
"examples": [
"Section Lead"
]
},
"email": {
"type": "string",
"maxLength": 60,
"description": "Email address. Required on create, even with `key_field=remote_id`. Can be changed on update but not cleared. The account's duplicate check (usually on `email`) rejects a value that belongs to another contact: `contact with email = {value} already exists`.",
"examples": [
"alto.lead@example.com"
]
},
"company": {
"type": "string",
"maxLength": 80,
"description": "Company or organisation. Too long: `Company must not exceed 80 characters`.",
"examples": [
"Harbourfront Choral Society",
""
]
},
"phone": {
"type": "string",
"maxLength": 25,
"description": "Phone number, free text with no format check. Too long: `Phone must not exceed 25 characters`.",
"examples": [
"416-555-0142"
]
},
"address_1": {
"type": "string",
"maxLength": 100,
"description": "Street address, line 1. Too long: `Address must not exceed 100 characters`.",
"examples": [
"48 Harbour Lane"
]
},
"address_2": {
"type": "string",
"maxLength": 100,
"description": "Street address, line 2. Too long: `Address 2 must not exceed 100 characters`.",
"examples": [
"Unit 5"
]
},
"city": {
"type": "string",
"maxLength": 50,
"description": "City. Too long: `City must not exceed 50 characters`.",
"examples": [
"Toronto"
]
},
"country": {
"type": "string",
"description": "Returned as a 2-letter ISO code, or `\"\"`. Accepts an ISO code (`CA`) or a recognised country name (`Canada`, `France`, `U.S.A.`, `UK`). An unrecognised value is not saved and produces the warning `'{value}' is not a valid value for country; field will not be updated`. Decides which consent rules apply; a contact with no country uses the account's default consent country. Cannot be cleared.",
"examples": [
"CA",
""
]
},
"province": {
"type": "string",
"maxLength": 50,
"description": "Province or state, free text. Too long: `Province must not exceed 50 characters`.",
"examples": [
"ON"
]
},
"postal_code": {
"type": "string",
"maxLength": 15,
"description": "Postal or ZIP code. Too long: `Postal / zip must not exceed 15 characters`.",
"examples": [
"M5V 0Z9"
]
},
"website": {
"type": "string",
"maxLength": 255,
"description": "Website URL, free text with no URL check. Too long: `Website must not exceed 255 characters`.",
"examples": [
"https://example.org",
""
]
},
"language": {
"type": "string",
"enum": [
"en",
"fr",
""
],
"description": "Preferred language, returned as `en`, `fr`, or `\"\"`. Accepts `en`, `fr`, `English`, or `French`, case-insensitive. Any other value is not saved and produces the warning `'{value}' is not a valid value for language; field will not be updated`. Cannot be cleared.",
"examples": [
"en"
]
},
"feedback": {
"type": "string",
"description": "Free-text notes. HTML tags are removed before the value is saved, without an error.",
"examples": [
"Happy to help with ushering at the winter concert.",
""
]
},
"consent_status": {
"type": "string",
"description": "Name of the contact's current consent type. Writable values: `Express`, `Implied - Inquiry`, `Implied - Transaction`, `Implied - No Expiry`, `Not Provided`, `Revoked`, `Envoke Spam Reported`. Read-only values set by Envoke: `Expired` (implied consent that has expired) and `External Spam Reported` (from a spam complaint). Older contacts can also carry the retired types `Implied - Existing Relationship`, `Legacy Subscribed`, `Legacy Confirmed`, or `Legacy Unknown`, which cannot be written. Defaults to `Not Provided` on create. A downgrade is recorded but not made current unless `consent_force_downgrade` is sent; changes away from a spam-reported type, and `Revoked` to `Not Provided`, are blocked. Neither is reported in the response.",
"examples": [
"Express"
]
},
"consent_description": {
"type": "string",
"maxLength": 500,
"description": "How and when consent was obtained. Text beyond 500 characters is cut off without an error. Never required.",
"examples": [
"Signed up at the spring concert"
]
},
"consent_effective_date": {
"type": "string",
"format": "date-time",
"description": "When the current consent took effect, W3C format in UTC. On write, a value without a time zone is read as UTC; a date with no time is read as midnight in Envoke's server time zone. Defaults to the time of the request. Must not be in the future (`consent_effective_date cannot be in the future.`); an unreadable value gives `Invalid date format for consent_effective_date`. Filterable with the range operators; not sortable.",
"examples": [
"2026-09-12T18:30:00+00:00"
]
},
"consent_expiry": {
"type": "string",
"readOnly": true,
"description": "Expiry date of the current consent as `YYYY-MM-DD`, or `\"\"`. `Implied - Inquiry` expires 6 months, and `Implied - Transaction` 2 years, after the effective date. On GET it is `\"\"` when the consent does not expire, when the contact's country is not `CA` (no country uses the account's default consent country), or when the account ignores consent expiry; create, upsert, and `PATCH /contacts` responses are not blanked. Ignored on write. Filterable with the range operators as a plain date; not sortable.",
"examples": [
"",
"2027-03-12"
]
},
"custom_fields": {
"type": "object",
"description": "Every custom field that has a value for the contact, keyed by the custom field's name exactly as defined in the account. `{}` when there are none. Lead-scope (conversion page) fields are not returned.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"Voice_Part": "Alto",
"Season_Ticket_Number": "HCS-ST-0417"
}
]
},
"interests": {
"type": "array",
"description": "Names of every tag, subscription, and mandatory consent item the contact has. `[]` when none.",
"items": {
"type": "string"
},
"examples": [
[
"Volunteer",
"Alumni",
"Concert News"
]
]
},
"autoresponders": {
"type": "array",
"description": "Names of the nurture campaigns (autoresponders) the contact is on. `[]` when none.",
"items": {
"type": "string"
},
"examples": [
[
"Welcome Sequence"
],
[]
]
}
}
},
"InterestsWrite": {
"description": "Tags, subscriptions, and mandatory consent items to write. A list of names adds each one and removes nothing. An object maps a name (or the item's numeric ID) to a state: `\"Set\"` or `1` adds, `\"Unset\"` or `0` removes. Names match ignoring case and treating a space and an underscore as the same. Numeric states must be JSON numbers; a string such as `\"1\"` is read as a name. Unknown name: `Invalid 'interest': '{name}' (for a list of valid interests try the endpoint '/interests')`. Wrong type: `'interests' must be an object or array`. Adding a subscription does not check the contact's sending consent; a `Not Provided` contact is subscribed like any other.",
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
},
"examples": [
[
"Volunteer",
"Concert News"
]
]
},
{
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"enum": [
"Set",
"Unset"
]
},
{
"type": "integer",
"enum": [
1,
0
]
}
]
},
"examples": [
{
"Volunteer": "Set",
"Alumni": "Unset"
}
]
}
]
},
"AutorespondersWrite": {
"description": "Nurture campaigns to write. A list of names adds and queues each one. An object maps a name (or the campaign's numeric ID) to a state: `\"Set\"`, `1`, or `2` adds and queues; `\"Unset\"` or `0` removes; `\"Dequeue\"` or `-1` stops further messages but leaves the contact on the campaign. Unknown name: `Invalid 'autoresponder': '{name}' (for a list of valid autoresponders try the endpoint '/autoresponders')`. Wrong type: `'autoresponders' must be an object or array`. A campaign is not added (the contact is not put on it) when the contact's consent does not allow sending, unless the campaign is transactional (never for a spam-reported contact); this is not reported. Campaigns cannot be created through the API.",
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
},
"examples": [
[
"Welcome Sequence"
]
]
},
{
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"enum": [
"Set",
"Unset",
"Dequeue"
]
},
{
"type": "integer",
"enum": [
2,
1,
0,
-1
]
}
]
},
"examples": [
{
"Welcome Sequence": "Dequeue"
}
]
}
]
},
"ContactWritable": {
"type": "object",
"description": "Writable contact fields shared by create and update. A key that is not a contact field gives `'{key}' is not a valid contact field`. `external_id`, `date_created`, and `consent_expiry` are read-only and silently ignored.",
"properties": {
"remote_id": {
"type": "string",
"maxLength": 60,
"examples": [
"HCS-0002"
]
},
"first_name": {
"type": "string",
"maxLength": 50,
"examples": [
"Maya"
]
},
"last_name": {
"type": "string",
"maxLength": 50,
"examples": [
"Okafor"
]
},
"title": {
"type": "string",
"maxLength": 50,
"examples": [
"Section Lead"
]
},
"email": {
"type": "string",
"maxLength": 60,
"description": "Must be a JSON string. Errors: `Email is required`, `Email must be a string`, `Email invalid`, `Email must not exceed 60 characters`; on update, `Email must not be empty`.",
"examples": [
"alto.lead@example.com"
]
},
"company": {
"type": "string",
"maxLength": 80,
"examples": [
"Harbourfront Choral Society"
]
},
"phone": {
"type": "string",
"maxLength": 25,
"examples": [
"416-555-0142"
]
},
"address_1": {
"type": "string",
"maxLength": 100,
"examples": [
"48 Harbour Lane"
]
},
"address_2": {
"type": "string",
"maxLength": 100,
"examples": [
"Unit 5"
]
},
"city": {
"type": "string",
"maxLength": 50,
"examples": [
"Toronto"
]
},
"country": {
"type": "string",
"description": "ISO code or recognised country name. Unrecognised values produce a warning and are not saved.",
"examples": [
"Canada",
"CA"
]
},
"province": {
"type": "string",
"maxLength": 50,
"examples": [
"ON"
]
},
"postal_code": {
"type": "string",
"maxLength": 15,
"examples": [
"M5V 0Z9"
]
},
"website": {
"type": "string",
"maxLength": 255,
"examples": [
"https://example.org"
]
},
"language": {
"type": "string",
"description": "`en`, `fr`, `English`, or `French`, case-insensitive. Other values produce a warning and are not saved.",
"examples": [
"English",
"en"
]
},
"feedback": {
"type": "string",
"description": "HTML is stripped.",
"examples": [
"Happy to help with ushering at the winter concert."
]
},
"consent_status": {
"type": "string",
"enum": [
"Express",
"Implied - Inquiry",
"Implied - Transaction",
"Implied - No Expiry",
"Not Provided",
"Revoked",
"Envoke Spam Reported"
],
"description": "Case-insensitive; a space and an underscore are treated as the same character. An unknown value gives `Invalid 'consent_status': '{value}' (possible values: 'Express', 'Implied - Inquiry', 'Implied - Transaction', 'Implied - No Expiry', 'Not Provided', 'Revoked', 'Envoke Spam Reported')`. Implied types do not apply to contacts in the EU consent region; a sentence is appended to `result_text` instead.",
"examples": [
"Express"
]
},
"consent_description": {
"type": "string",
"maxLength": 500,
"examples": [
"Signed up at the spring concert"
]
},
"consent_effective_date": {
"type": "string",
"description": "Date and time, e.g. `2026-09-12T18:30:00Z` or `2026-09-12 18:30:00` (UTC). Not in the future.",
"examples": [
"2026-09-12T18:30:00Z"
]
},
"consent_force_downgrade": {
"type": [
"boolean",
"string",
"integer"
],
"writeOnly": true,
"description": "Sent with `consent_status` to make a preempted downgrade current. True for `true`, `\"true\"`, `1`, `\"1\"`, `\"yes\"`, `\"on\"`, or `\"Set\"`; anything else is false. Does nothing on its own, on a new contact, or for blocked changes. Never returned.",
"examples": [
true
]
},
"custom_fields": {
"type": "object",
"description": "Values keyed by custom field name; matching ignores case and treats a space and an underscore as the same. IDs are not accepted as keys. Values are stored as text and not checked against the field's type. `\"\"` deletes the value; a value that cannot be stored (e.g. `null`) is skipped without an error. Fields not included are left unchanged. Unknown key: `Invalid 'custom_field': '{name}' (for a list of valid custom fields try the endpoint '/customfields')`. Not an object: `'custom_fields' must be an object`.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"Voice_Part": "Alto",
"Season_Ticket_Number": "HCS-ST-0417"
}
]
},
"interests": {
"$ref": "#/components/schemas/InterestsWrite"
},
"autoresponders": {
"$ref": "#/components/schemas/AutorespondersWrite"
}
}
},
"ContactCreate": {
"description": "Request body for `POST /contacts`: a single JSON object. `email` is required; `remote_id` is also required with `key_field=remote_id`. `id` is ignored. A missing `consent_status` becomes `Not Provided` on a new contact.",
"allOf": [
{
"$ref": "#/components/schemas/ContactWritable"
},
{
"type": "object",
"required": [
"email"
]
}
]
},
"ContactUpdate": {
"description": "Request body for one contact in a PATCH. Send only the fields to change; only fields that differ from the stored value are written, and a request that changes nothing still succeeds. `id` identifies the contact and is never written.",
"allOf": [
{
"$ref": "#/components/schemas/ContactWritable"
},
{
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
],
"description": "On `PATCH /contacts/{id}`, must equal the URL id if sent (`\"1001\"` and `1001` count as the same). On `PATCH /contacts` without `key_field`, and in a list body, used directly without a lookup.",
"examples": [
1001
]
}
}
}
]
},
"V1ContactsCreateSuccessResponse": {
"type": "object",
"description": "Returned by a create, and by an upsert whether it creates or updates. `result_data` is the full contact. Warnings are appended to `result_text`: after a space, joined with `. `, on create; after `. ` (a double period) when an upsert updates. For an EU contact given an implied type, a consent sentence is appended in the same way.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"examples": [
"The contact was successfully created.",
"The contact was successfully updated."
]
},
"result_data": {
"$ref": "#/components/schemas/Contact"
}
}
},
"UpdateByIdSuccessResponse": {
"type": "object",
"description": "Returned by `PATCH /contacts/{id}`. A short result, not the full contact.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"description": "`The contact was successfully updated.`, followed by a consent sentence when an EU rule applied.",
"examples": [
"The contact was successfully updated."
]
},
"result_data": {
"type": "object",
"required": [
"id",
"submit_type",
"warnings"
],
"properties": {
"id": {
"type": "integer",
"description": "The contact ID, as an integer on this endpoint.",
"examples": [
1001
]
},
"submit_type": {
"type": "string",
"const": "update"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "`country` and `language` warnings; `[]` when none.",
"examples": [
[],
[
"'Narnia' is not a valid value for country; field will not be updated"
]
]
},
"no_affected_rows": {
"type": "boolean",
"const": true,
"description": "Present when no profile column changed (only custom fields, tags, nurture campaigns, or consent, or nothing at all)."
},
"inapplicable_consent_updated": {
"type": "boolean",
"const": true,
"description": "Present when a change of `country` to an EU country reset an implied consent type to `Not Provided`."
},
"consent_fix_message": {
"type": "string",
"description": "Present with `inapplicable_consent_updated`; the sentence also appended to `result_text`.",
"examples": [
" Their consent status was updated because Implied - Inquiry consent does not apply to contacts in the EU."
]
}
}
}
}
},
"UpdateByKeySuccessResponse": {
"type": "object",
"description": "Returned by `PATCH /contacts` with an object body. `result_data` is the full, updated contact. Warnings are appended to `result_text` after `. `, which follows the success message's own period.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"examples": [
"The contact was successfully updated.",
"The contact was successfully updated.. 'Narnia' is not a valid value for country; field will not be updated"
]
},
"result_data": {
"$ref": "#/components/schemas/Contact"
}
}
},
"BulkUpdateResponse": {
"type": "object",
"description": "Returned by `PATCH /contacts` (or `PATCH /contacts/{id}`, whose id is then ignored) with a list body. HTTP 200 when every contact was updated; HTTP 400 with `success: false` when any failed, even though the others were updated.",
"required": [
"success",
"successes",
"failures",
"result_data",
"result_text"
],
"properties": {
"success": {
"type": "boolean"
},
"successes": {
"type": "array",
"items": {
"type": [
"string",
"integer"
]
},
"description": "IDs of the contacts that were updated.",
"examples": [
[
"1006",
"1007"
]
]
},
"failures": {
"type": "array",
"items": {
"type": [
"string",
"integer"
]
},
"description": "IDs of contacts that were found but failed, and `CONTACT_OBJECT_{n}` (zero-based list position) for contacts that could not be found.",
"examples": [
[
"CONTACT_OBJECT_2"
]
]
},
"result_data": {
"type": "object",
"description": "Each contact's result keyed by contact ID or `CONTACT_OBJECT_{n}`. A found contact has the `result_data` of `PATCH /contacts/{id}` (or its `errors`, or `fields` and `warnings`); a contact that could not be found has `errors` with the lookup error.",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"submit_type": {
"type": "string"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
},
"fields": {
"type": [
"object",
"array"
]
}
}
}
},
"result_text": {
"type": "string",
"examples": [
"All contacts were successfully updated",
"2 contacts were successfully updated; 1 contacts were not updated"
]
}
}
},
"V1ContactsDeleteResponse": {
"type": "object",
"description": "Returned by DELETE, on success and on failure. There is no `result_data` key.",
"required": [
"success",
"result_text"
],
"additionalProperties": false,
"properties": {
"success": {
"type": "boolean"
},
"result_text": {
"type": "string",
"examples": [
"1 contact deleted",
"1 contact not deleted, 1 - no matching contact found",
"1 contact not deleted, 1 - can't delete due to consent status"
]
}
}
},
"V1ContactsValidationErrorResponse": {
"type": "object",
"description": "Body, query, and not-found-by-id errors. Every problem found by the check is listed.",
"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"
}
}
}
}
}
},
"FieldValidationErrorResponse": {
"type": "object",
"description": "Field lengths, email format, and the account's duplicate check, which run after the body checks. `result_data.fields` is keyed by database column (`first_name` is `fname`, `last_name` `lname`, `address_1` `addr1`, `address_2` `addr2`, `postal_code` `postal`, `external_id` `eid`; others match the API name), and `result_text` holds the messages joined with `, `. A duplicate-check failure has `fields: []`. On update, the envelope also carries `warnings`.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": false
},
"result_text": {
"type": "string",
"examples": [
"Email invalid, First name must not exceed 50 characters",
"contact with email = alto.lead@example.com already exists"
]
},
"result_data": {
"type": "object",
"required": [
"fields"
],
"properties": {
"fields": {
"type": [
"object",
"array"
],
"additionalProperties": {
"type": "string"
},
"examples": [
{
"email": "Email invalid",
"fname": "First name must not exceed 50 characters"
},
[]
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"V1ContactsPlainErrorResponse": {
"type": "object",
"description": "Request-shape and lookup errors: the message is in `result_text` and `result_data` is an empty array.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": false
},
"result_text": {
"type": "string",
"examples": [
"Invalid request",
"Invalid JSON",
"Contact 'id': 1001 does not match 'id' in request body (1002)",
"No contact was found with the 'email': 'nobody@example.com'"
]
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"Tag": {
"type": "object",
"description": "A tag (interest) definition.",
"required": [
"id",
"external_id",
"name",
"group",
"description",
"display_names"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Unique identifier assigned on creation. Returned as a string.",
"examples": [
"42"
]
},
"external_id": {
"type": "string",
"readOnly": true,
"description": "Externally visible identifier used in public-facing integrations.",
"examples": [
"a1b2c3d4e5f6"
]
},
"name": {
"type": "string",
"description": "The tag name.",
"examples": [
"Newsletter Subscribers"
]
},
"group": {
"type": "string",
"description": "Name of the group the tag belongs to. Empty string (`\"\"`) when no group is assigned.",
"examples": [
"Member Programs",
""
]
},
"description": {
"type": "string",
"description": "Internal description of the tag. Not visible to contacts. Empty string when not set.",
"examples": [
"Members interested in the annual conference"
]
},
"display_names": {
"type": "object",
"description": "Translated display labels keyed by ISO language code. Used in public-facing contexts such as website forms. Values are empty strings when no translation is set.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Newsletter",
"fr": "Infolettre"
}
]
}
}
},
"TagCreate": {
"type": "object",
"description": "Request body for creating a new tag. `name` is required.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The tag name.",
"examples": [
"Newsletter Subscribers"
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Group to assign the tag to. Accepts the group name (string) or group ID (integer). The group must be of type `interest`.",
"examples": [
"Member Programs",
5
]
},
"description": {
"type": "string",
"description": "Internal description of the tag.",
"examples": [
"Members interested in the annual conference"
]
},
"display_names": {
"type": "object",
"description": "Translated display labels keyed by ISO language code.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Newsletter",
"fr": "Infolettre"
}
]
}
}
},
"TagUpdate": {
"type": "object",
"description": "Request body for updating a tag. At least one field must be provided. `external_id` is silently ignored if included. If `id` is included, it must match the `{id}` in the URL.",
"minProperties": 1,
"properties": {
"id": {
"type": [
"integer",
"string"
],
"description": "Optional. If provided, must match the `{id}` in the URL. A mismatch returns a validation envelope.",
"examples": [
42
]
},
"name": {
"type": "string",
"description": "New name for the tag.",
"examples": [
"Updated Tag Name"
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Group to assign the tag to. Accepts group name or group ID. Pass `\"\"` (empty string) to remove the group assignment.",
"examples": [
"Certification Programs",
""
]
},
"description": {
"type": "string",
"description": "Updated internal description.",
"examples": [
"Updated description"
]
},
"display_names": {
"type": "object",
"description": "Translated display labels keyed by ISO language code.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Organic",
"fr": "Biologique"
}
]
}
}
},
"ContactsRequest": {
"type": "object",
"description": "Request body for adding or removing contacts. Provide exactly one of `contact_ids` or `contact_emails`.",
"oneOf": [
{
"required": [
"contact_ids"
],
"properties": {
"contact_ids": {
"type": "array",
"items": {
"type": "integer"
},
"minItems": 1,
"maxItems": 1000,
"description": "Envoke contact IDs to add or remove.",
"examples": [
[
101,
102,
103
]
]
}
}
},
{
"required": [
"contact_emails"
],
"properties": {
"contact_emails": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 1000,
"description": "Contact email addresses to add or remove.",
"examples": [
[
"alice@example.com",
"bob@example.com"
]
]
}
}
}
]
},
"ContactsSuccessResponse": {
"type": "object",
"description": "Returned after a contacts add or remove operation.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"description": "`true` if no found contacts failed to update. `true` even when some identifiers were not found."
},
"result_text": {
"type": "string",
"description": "Human-readable summary.",
"examples": [
"Set to contacts",
"Set to contacts. Some contacts not found",
"Error setting to contacts"
]
},
"result_data": {
"type": "object",
"required": [
"processed"
],
"properties": {
"processed": {
"type": "integer",
"description": "Total number of input identifiers submitted."
},
"not_found": {
"type": "array",
"description": "IDs or emails that were not matched to any contact. Only present when at least one was not found.",
"items": {
"type": [
"string",
"integer"
]
}
},
"failed": {
"type": "array",
"description": "Contacts that were found but failed during the update. Only present when failures occurred.",
"items": {
"type": "object",
"required": [
"contact_id",
"reason"
],
"properties": {
"contact_id": {
"type": [
"string",
"integer"
]
},
"reason": {
"type": "string"
}
}
}
}
}
}
}
},
"V2TagsCreateSuccessResponse": {
"type": "object",
"description": "Returned on successful tag creation.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Created"
},
"result_data": {
"$ref": "#/components/schemas/Tag"
}
}
},
"V2TagsUpdateSuccessResponse": {
"type": "object",
"description": "Returned on successful tag update.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Updated"
},
"result_data": {
"$ref": "#/components/schemas/Tag"
}
}
},
"V2TagsDeleteSuccessResponse": {
"type": "object",
"description": "Returned on successful tag deletion.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Deleted"
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"V2TagsValidationErrorResponse": {
"type": "object",
"description": "Returned when request body or path parameter validation fails.",
"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"
},
"description": "One or more human-readable validation error messages."
}
}
}
}
},
"Subscription": {
"type": "object",
"description": "A subscription definition.",
"required": [
"id",
"external_id",
"name",
"group",
"prefpage_access",
"display_names",
"display_descriptions"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Unique identifier assigned on creation. Returned as a string.",
"examples": [
"12"
]
},
"external_id": {
"type": "string",
"readOnly": true,
"description": "Externally visible identifier used in public-facing integrations.",
"examples": [
"a1b2c3d4e5f6"
]
},
"name": {
"type": "string",
"description": "The subscription name.",
"examples": [
"Campus Weekly Newsletter"
]
},
"group": {
"type": "string",
"description": "Name of the group the subscription belongs to. Empty string (`\"\"`) when no group is assigned.",
"examples": [
"Student Communications",
""
]
},
"prefpage_access": {
"type": "string",
"enum": [
"public",
"private"
],
"description": "Controls whether this subscription appears on the public preference page. `\"public\"` (default) means it is visible to contacts. `\"private\"` hides it from public preference pages — requires the private subscriptions feature.",
"examples": [
"public"
]
},
"display_names": {
"type": "object",
"description": "Translated display labels keyed by ISO language code. Shown to contacts on the preference page. Values are empty strings when no translation is set. All enabled account languages are included as keys.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Campus Weekly Newsletter",
"fr": "Bulletin hebdomadaire du campus"
}
]
},
"display_descriptions": {
"type": "object",
"description": "Translated descriptions keyed by ISO language code. Shown alongside the display name on the preference page. Values are empty strings when no translation is set. All enabled account languages are included as keys.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "A weekly roundup of campus news and events.",
"fr": "Un résumé hebdomadaire des nouvelles et événements du campus."
}
]
}
}
},
"SubscriptionCreate": {
"type": "object",
"description": "Request body for creating a new subscription. `name` is required.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The subscription name.",
"examples": [
"Campus Weekly Newsletter"
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Group to assign the subscription to. Accepts the group name (string) or group ID (integer). The group must be of type `subscription`.",
"examples": [
"Student Communications",
5
]
},
"prefpage_access": {
"type": "string",
"enum": [
"public",
"private"
],
"description": "Preference page visibility. Defaults to `\"public\"`. Setting to `\"private\"` requires the private subscriptions feature.",
"examples": [
"public"
]
},
"display_names": {
"type": "object",
"description": "Translated display labels keyed by ISO language code.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Campus Weekly Newsletter",
"fr": "Bulletin hebdomadaire du campus"
}
]
},
"display_descriptions": {
"type": "object",
"description": "Translated descriptions keyed by ISO language code.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "A weekly roundup of campus news and events."
}
]
}
}
},
"SubscriptionUpdate": {
"type": "object",
"description": "Request body for updating a subscription. At least one field must be provided. `external_id` is silently ignored if included. If `id` is included, it must match the `{id}` in the URL — if they differ, a validation envelope is returned.",
"minProperties": 1,
"properties": {
"id": {
"type": [
"integer",
"string"
],
"description": "Optional. If provided, must match the `{id}` in the URL. A mismatch returns a validation envelope.",
"examples": [
12
]
},
"name": {
"type": "string",
"description": "New name for the subscription.",
"examples": [
"Updated Subscription Name"
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Group to assign the subscription to. Accepts group name or group ID. Pass `\"\"` (empty string) to remove the group assignment.",
"examples": [
"Alumni Relations",
""
]
},
"prefpage_access": {
"type": "string",
"enum": [
"public",
"private"
],
"description": "Preference page visibility. Setting to `\"private\"` requires the private subscriptions feature.",
"examples": [
"public"
]
},
"display_names": {
"type": "object",
"description": "Translated display labels keyed by ISO language code.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Updated Subscription Name"
}
]
},
"display_descriptions": {
"type": "object",
"description": "Translated descriptions keyed by ISO language code.",
"additionalProperties": {
"type": "string"
},
"examples": [
{
"en": "Updated description."
}
]
}
}
},
"V2SubscriptionsCreateSuccessResponse": {
"type": "object",
"description": "Returned on successful subscription creation.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Created"
},
"result_data": {
"$ref": "#/components/schemas/Subscription"
}
}
},
"V2SubscriptionsUpdateSuccessResponse": {
"type": "object",
"description": "Returned on successful subscription update.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Updated"
},
"result_data": {
"$ref": "#/components/schemas/Subscription"
}
}
},
"V2SubscriptionsDeleteSuccessResponse": {
"type": "object",
"description": "Returned on successful subscription deletion.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Deleted"
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"V2SubscriptionsValidationErrorResponse": {
"type": "object",
"description": "Returned when request body or path parameter validation fails.",
"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"
},
"description": "One or more human-readable validation error messages."
}
}
}
}
},
"CustomField": {
"type": "object",
"description": "A contact-scoped custom field definition.",
"required": [
"id",
"name",
"description",
"field_type"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Unique identifier assigned on creation. Returned as a string.",
"examples": [
"42"
]
},
"name": {
"type": "string",
"readOnly": true,
"description": "The field identifier. Contains only alphanumeric characters and underscores. Unique per account.",
"examples": [
"phone_number"
]
},
"description": {
"type": "string",
"description": "Human-readable description of the field. Returns an empty string when not set.",
"examples": [
"Customer's mobile phone number",
""
]
},
"field_type": {
"type": "string",
"readOnly": true,
"enum": [
"text",
"note",
"date",
"url"
],
"description": "The data type of values stored in this field. Read-only after creation.",
"examples": [
"text"
]
}
}
},
"CustomFieldCreate": {
"type": "object",
"description": "Request body for creating a new custom field.",
"required": [
"name",
"field_type"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"description": "The field identifier. Alphanumeric characters and underscores only. Must be unique per account.",
"examples": [
"phone_number"
]
},
"field_type": {
"type": "string",
"enum": [
"text",
"note",
"date",
"url"
],
"description": "The data type for values stored in this field. Cannot be changed after creation.",
"examples": [
"text"
]
},
"description": {
"type": "string",
"description": "Optional human-readable description of the field.",
"examples": [
"Customer's mobile phone number"
]
}
}
},
"CustomFieldUpdate": {
"type": "object",
"description": "Request body for updating an existing custom field. At least one property must be provided. `field_type` cannot be changed.",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"description": "New name for the field. Alphanumeric characters and underscores only. Must be unique per account.",
"examples": [
"mobile_number"
]
},
"description": {
"type": "string",
"description": "Updated description for the field.",
"examples": [
"Customer's mobile phone number"
]
}
}
},
"V2CustomfieldsCreateSuccessResponse": {
"type": "object",
"description": "Returned on successful creation.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Created"
},
"result_data": {
"$ref": "#/components/schemas/CustomField"
}
}
},
"V2CustomfieldsUpdateSuccessResponse": {
"type": "object",
"description": "Returned on successful update.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Updated"
},
"result_data": {
"$ref": "#/components/schemas/CustomField"
}
}
},
"V2CustomfieldsDeleteSuccessResponse": {
"type": "object",
"description": "Returned on successful deletion.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Deleted"
},
"result_data": {
"type": "array",
"maxItems": 0,
"description": "Always an empty array on deletion."
}
}
},
"V2CustomfieldsValidationErrorResponse": {
"type": "object",
"description": "Returned when request body validation fails.",
"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"
},
"description": "One or more human-readable validation error messages."
}
}
}
}
},
"V2CustomfieldsErrorResponse": {
"type": "object",
"description": "Returned for general errors (e.g. not found, bad request).",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": false
},
"result_text": {
"type": "string",
"description": "Human-readable summary of the error.",
"examples": [
"Item with id '42' not found",
"An 'id' must be provided in order to update"
]
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"Group": {
"type": "object",
"description": "A group definition.",
"required": [
"id",
"name",
"parent_group"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Unique identifier assigned on creation. Returned as a string.",
"examples": [
"7"
]
},
"name": {
"type": "string",
"description": "The group name.",
"examples": [
"Academic Programs"
]
},
"parent_group": {
"type": "string",
"description": "Name of the parent group. Empty string (`\"\"`) when the group is top-level (has no parent).",
"examples": [
"Academic Programs",
""
]
}
}
},
"GroupCreate": {
"type": "object",
"description": "Request body for creating a new group. `name` is required.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The group name.",
"examples": [
"Academic Programs"
]
},
"parent_group": {
"type": [
"string",
"integer",
"null"
],
"description": "Parent group name (string) or parent group ID (integer) to nest this group under. Omit, pass `null`, or pass `\"\"` to create a top-level group. The parent must itself be a top-level group — nesting deeper than one level is not supported.",
"examples": [
"Academic Programs",
7,
null
]
}
}
},
"GroupUpdate": {
"type": "object",
"description": "Request body for updating a group. At least one field must be provided. If `id` is included, it must match the `{id}` in the URL.",
"minProperties": 1,
"properties": {
"id": {
"type": [
"integer",
"string"
],
"description": "Optional. If provided, must match the `{id}` in the URL. A mismatch returns a validation envelope.",
"examples": [
7
]
},
"name": {
"type": "string",
"description": "New name for the group.",
"examples": [
"Updated Group Name"
]
},
"parent_group": {
"type": [
"string",
"integer",
"null"
],
"description": "Parent group name or ID to assign. Pass `null` or `\"\"` to promote the group to top-level (remove its parent). The parent must itself be top-level.",
"examples": [
"Academic Programs",
7,
null,
""
]
}
}
},
"V2GroupsCreateSuccessResponse": {
"type": "object",
"description": "Returned on successful group creation.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Created"
},
"result_data": {
"$ref": "#/components/schemas/Group"
}
}
},
"V2GroupsUpdateSuccessResponse": {
"type": "object",
"description": "Returned on successful group update.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Updated"
},
"result_data": {
"$ref": "#/components/schemas/Group"
}
}
},
"V2GroupsDeleteSuccessResponse": {
"type": "object",
"description": "Returned on successful group deletion.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Deleted"
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"V2GroupsValidationErrorResponse": {
"type": "object",
"description": "Returned when request body or path parameter validation fails.",
"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"
},
"description": "One or more human-readable validation error messages."
}
}
}
}
},
"Template": {
"type": "object",
"description": "An email template definition.",
"required": [
"id",
"external_id",
"preview_url",
"name",
"status",
"language",
"group",
"create_time",
"modified_time"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Unique identifier assigned on creation. Returned as a string.",
"examples": [
"42"
]
},
"external_id": {
"type": "string",
"readOnly": true,
"description": "Randomly assigned external identifier used to construct the preview URL.",
"examples": [
"a1b2c3d4e5f6g7h8"
]
},
"preview_url": {
"type": "string",
"readOnly": true,
"description": "Public URL to preview the template. Built on the account's custom domain when it has one, otherwise Envoke's message domain (not the API host), from the account's external ID and the template's external_id.",
"examples": [
"https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6g7h8"
]
},
"name": {
"type": "string",
"minLength": 3,
"description": "The template name. Minimum 3 characters.",
"examples": [
"Welcome Email"
]
},
"status": {
"type": "string",
"enum": [
"published",
"unpublished"
],
"description": "Publication status of the template. New templates are always created as `published`.",
"examples": [
"published"
]
},
"language": {
"type": "string",
"description": "IETF language code for the template (e.g. `en`, `fr`). Defaults to `en`.",
"examples": [
"en"
]
},
"group": {
"type": "string",
"description": "Name of the group the template belongs to. Empty string (`\"\"`) when no group is assigned.",
"examples": [
"Marketing Templates",
""
]
},
"create_time": {
"type": "string",
"readOnly": true,
"description": "Timestamp when the template was created, in the account's configured timezone. Format: `Y-m-d H:i:s`.",
"examples": [
"2026-04-11 09:00:00"
]
},
"modified_time": {
"type": "string",
"readOnly": true,
"description": "Timestamp when the template was last modified, in the account's configured timezone. Format: `Y-m-d H:i:s`.",
"examples": [
"2026-04-11 14:22:10"
]
}
}
},
"TemplateWithHTML": {
"allOf": [
{
"$ref": "#/components/schemas/Template"
},
{
"type": "object",
"required": [
"html"
],
"properties": {
"html": {
"type": "string",
"description": "Full HTML content of the template. Only present when `?include_html=1` is passed on a single-template GET request.",
"examples": [
"Hello!
"
]
}
}
}
]
},
"TemplateCreate": {
"type": "object",
"description": "Request body for creating a new template. Either `html` or `template_id` must be provided. `name` is optional — if omitted, it is auto-generated as `API Template {timestamp}`.",
"properties": {
"name": {
"type": "string",
"minLength": 3,
"description": "The template name. Minimum 3 characters. Auto-generated if omitted.",
"examples": [
"Welcome Email"
]
},
"html": {
"type": "string",
"description": "Full HTML content of the template. Maximum 200 KB. Required if `template_id` is not provided.",
"examples": [
"Welcome!
"
]
},
"template_id": {
"type": "integer",
"description": "ID of an existing template or message to copy HTML from. Required if `html` is not provided. Must be owned by your account or accessible as a shared template.",
"examples": [
10
]
},
"language": {
"type": [
"string",
"integer"
],
"description": "Language for the template. Accepts an IETF language code (e.g. `en`, `fr`) or a numeric language ID. Defaults to `en` if omitted.",
"examples": [
"en",
1
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Group to assign the template to. Accepts the group name (string) or group ID (integer). The group must be of type `message_template`.",
"examples": [
"Marketing Templates",
5
]
}
}
},
"TemplateUpdate": {
"type": "object",
"description": "Request body for updating a template. At least one field must be provided. `external_id`, `preview_url`, `create_time`, and `modified_time` are silently ignored if included. `id` in the request body is validated against the URL id — if they differ, an error is returned.",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 3,
"description": "New name for the template. Minimum 3 characters.",
"examples": [
"Updated Welcome Email"
]
},
"status": {
"type": "string",
"enum": [
"published",
"unpublished"
],
"description": "New publication status.",
"examples": [
"unpublished"
]
},
"language": {
"type": [
"string",
"integer"
],
"description": "Language for the template. Accepts an IETF language code or numeric language ID.",
"examples": [
"fr"
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Group to assign the template to. Accepts group name or group ID. Pass an empty string (`\"\"`) to remove the group assignment.",
"examples": [
"Seasonal Campaigns",
""
]
},
"html": {
"type": "string",
"description": "Replacement HTML content for the template. Maximum 200 KB.",
"examples": [
"Updated content
"
]
}
}
},
"V2TemplatesCreateSuccessResponse": {
"type": "object",
"description": "Returned on successful template creation.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Created"
},
"result_data": {
"$ref": "#/components/schemas/Template"
}
}
},
"V2TemplatesUpdateSuccessResponse": {
"type": "object",
"description": "Returned on successful template update.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Updated"
},
"result_data": {
"$ref": "#/components/schemas/Template"
}
}
},
"V2TemplatesDeleteSuccessResponse": {
"type": "object",
"description": "Returned on successful deletion. Templates are soft-deleted.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": true
},
"result_text": {
"type": "string",
"const": "Deleted"
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"V2TemplatesValidationErrorResponse": {
"type": "object",
"description": "Returned when request body or path parameter validation fails.",
"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"
},
"description": "One or more human-readable validation error messages."
},
"allowed_values": {
"type": "object",
"description": "Present on some errors. Maps a field name to its allowed values.",
"additionalProperties": true
}
}
}
}
},
"V2TemplatesErrorResponse": {
"type": "object",
"description": "Returned for general request errors.",
"required": [
"success",
"result_text",
"result_data"
],
"properties": {
"success": {
"type": "boolean",
"const": false
},
"result_text": {
"type": "string"
},
"result_data": {
"type": "array",
"maxItems": 0
}
}
},
"Message": {
"type": "object",
"description": "A message as returned by GET and by the create, update, and cancel responses. Every readable field is present unless `fields` selects some. An unset text value is `\"\"`, except `sender` and `reply_to`, which are `null` when no identity is set. `html` is present only on a single GET with `include_html=1`, as the last key.",
"required": [
"id",
"external_id",
"preview_url",
"create_time",
"modified_time",
"name",
"group",
"status",
"send_time",
"sender",
"reply_to",
"subject",
"language",
"recipient_subscription",
"recipient_tag",
"recipient_segment",
"recipient_language",
"publish_archive",
"utm_tag_links"
],
"properties": {
"id": {
"type": "string",
"readOnly": true,
"description": "Envoke message ID, assigned on creation. Returned as a string (the one exception is `result_data.id` of `POST /messages/send`). Ignored on write.",
"examples": [
"2001"
]
},
"external_id": {
"type": "string",
"readOnly": true,
"minLength": 32,
"maxLength": 32,
"description": "32-character externally visible identifier used to build `preview_url`. Not the same as `id`. Ignored on write.",
"examples": [
"3e8b1f6c9a2d4e7b0c5f8a1d3e6b9c2f"
]
},
"preview_url": {
"type": "string",
"format": "uri",
"readOnly": true,
"description": "Public URL that shows the message in a browser without logging in: `https://{domain}/m/{account_external_id}/m/{external_id}`, where `{domain}` is the account's custom domain if it has one and otherwise Envoke's message domain (not the API host). Ignored on write.",
"examples": [
"https://engage.envoke.com/m/a7c3e9f1b5d2/m/3e8b1f6c9a2d4e7b0c5f8a1d3e6b9c2f"
]
},
"create_time": {
"type": "string",
"readOnly": true,
"description": "When the message was created, `Y-m-d H:i:s` in the account time zone with no offset. Ignored on write. Sortable, not filterable.",
"examples": [
"2026-10-06 10:15:42"
]
},
"modified_time": {
"type": "string",
"readOnly": true,
"description": "When the message was last changed, `Y-m-d H:i:s` in the account time zone with no offset. Changes on every successful update (even one that changes no value), send, and cancel. The list is sorted by this field, newest first, by default. Ignored on write. Sortable, not filterable.",
"examples": [
"2026-10-06 11:02:08"
]
},
"name": {
"type": "string",
"minLength": 3,
"description": "Internal name shown in the Envoke message list; recipients do not see it. At least 3 characters (`The field 'name' must be at least 3 characters long`); a longer name is cut to its first 300 characters without an error. Generated as `API Message {Y-m-d H:i:s}` from Envoke's server clock when omitted on create.",
"examples": [
"Spring Season Announcement"
]
},
"group": {
"type": "string",
"description": "Name of the message group (folder), or `\"\"` when the message has no group.",
"examples": [
"Productions",
""
]
},
"status": {
"type": "string",
"readOnly": true,
"enum": [
"Draft",
"Scheduled",
"AB test in progress",
"Queuing",
"Sending",
"Transactional",
"Nurture",
"Sent"
],
"description": "Current status, returned by name. Codes: `Draft` 0, `Scheduled` 1, `AB test in progress` 2, `Queuing` 4, `Sending` 5, `Transactional` 7, `Nurture` 8, `Sent` 9. Changed only by sending and cancelling; ignored on write. Only a `Draft` can be updated or sent. Filterable by name or code.",
"examples": [
"Draft"
]
},
"send_time": {
"type": "string",
"description": "Scheduled send time, `Y-m-d H:i:s` in the account time zone, or `\"\"` when no time is set. Setting it on a draft does not schedule the message. Once set it cannot be cleared, and it survives a cancel.",
"examples": [
"2026-10-20 09:00:00",
""
]
},
"sender": {
"type": [
"string",
"null"
],
"description": "Sender identity as `Name `, or `null` when no identity is set. Defaults to the account's default sender on create.",
"examples": [
"Box Office "
]
},
"reply_to": {
"type": [
"string",
"null"
],
"description": "Reply-to identity as `Name `, or `null` when no identity is set (the default). When not set, replies go to the sender address.",
"examples": [
"Front of House ",
null
]
},
"subject": {
"type": "string",
"description": "Subject line, or `\"\"`. Required to send.",
"examples": [
"Our spring season is here"
]
},
"language": {
"type": "string",
"enum": [
"en",
"fr"
],
"description": "Language the message is written in. Defaults to `en`.",
"examples": [
"en"
]
},
"recipient_subscription": {
"type": "string",
"description": "Name of the subscription the message is sent to, or `\"\"`.",
"examples": [
"Season News",
""
]
},
"recipient_tag": {
"type": "string",
"description": "Name of the tag the message is sent to, or `\"\"`. `\"\"` when the message is sent to a subscription alone.",
"examples": [
"Cast Call",
""
]
},
"recipient_segment": {
"type": "string",
"description": "Name of the segment the message is sent to, or `\"\"`.",
"examples": [
"Lapsed Subscribers",
""
]
},
"recipient_language": {
"type": "string",
"enum": [
"en",
"fr",
""
],
"description": "Only contacts with this language are sent the message; `\"\"` for all languages. When it matches the account's default language, contacts with no language set are included too.",
"examples": [
"",
"fr"
]
},
"publish_archive": {
"type": "boolean",
"description": "Whether the message is published to the account's public message archive. Defaults to `false`.",
"examples": [
true
]
},
"utm_tag_links": {
"type": "boolean",
"description": "Whether UTM tracking parameters are added to the links in the message. Defaults on create to the account's link analytics preference.",
"examples": [
true
]
},
"html": {
"type": "string",
"description": "The message HTML. Present only on `GET /messages/{id}?include_html=1`, as the last key.",
"examples": [
"The Pirates of Penzance
Curtain at 7:30 p.m.
"
]
}
}
},
"V2MessagesReplace": {
"type": "object",
"description": "Placeholder text to replace in the message HTML once, when the message is saved; the HTML is stored with the replacements made and nothing is replaced at send time. 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. Keys are applied in the order sent, so a later key can match text inserted by an earlier value. A key that does not appear in the HTML is ignored, and `{}` is ignored. A key may not contain `{@pref-`, `{@consent-url`, or `{@consent-prefpage-url`. Any other shape (a list, a non-string value, a key without braces, a protected key) fails with `Invalid 'replace' data`. On create it applies to `html` or to the HTML copied through `template_id`; on update it needs `html` in the same request (`The field 'html' is required for content 'replace' data`). Envoke merge tags such as `{@first_name}` are not protected; avoid them as keys. Never returned.",
"propertyNames": {
"pattern": "^\\{.+\\}$"
},
"additionalProperties": {
"type": "string"
},
"examples": [
{
"{SHOW_TITLE}": "The Pirates of Penzance",
"{CURTAIN_TIME}": "7:30 p.m."
}
]
},
"MessageWritable": {
"type": "object",
"description": "Writable message fields shared by create, update, send, and cancel bodies. `id` (on create), `external_id`, `preview_url`, `create_time`, `modified_time`, and `status` are read-only and silently ignored. Any other key gives `'{key}' is not a valid field`. Lookup fields (`group`, `sender`, `reply_to`, `language`, `recipient_*`) are cleared with `\"\"` or the string `\"0\"`; a JSON number `0` fails as an invalid value (e.g. `Invalid 'group': '0'`).",
"properties": {
"name": {
"type": "string",
"minLength": 3,
"description": "At least 3 characters: `The field 'name' must be at least 3 characters long`. Cannot be cleared.",
"examples": [
"Spring Season Announcement"
]
},
"group": {
"type": [
"string",
"integer"
],
"description": "Name or ID of an existing message group. Names are matched ignoring case, with a space and an underscore treated as the same. Groups are not created automatically; template and contact groups are not accepted. Unknown: `Invalid 'group': '{value}'` with `allowed_values.group`. `\"\"` or `\"0\"` removes the group.",
"examples": [
"Productions",
31
]
},
"subject": {
"type": "string",
"minLength": 6,
"description": "At least 6 characters: `The field 'subject' must be at least 6 characters long`; a longer subject is cut to its first 360 characters without an error. Required to send. Cannot be cleared.",
"examples": [
"Our spring season is here"
]
},
"sender": {
"type": [
"string",
"integer"
],
"description": "A sender identity, resolved in this order: an identity ID (`412`); `Name ` matching an identity, ignoring case and treating a space and an underscore as the same; `\"\"` or `\"0\"` clears it (on update, with no fallback to the default, and the message cannot then be sent: `The field 'sender' must be set`); an email address, matched exactly including case against the first identity with that address (`No sender identity found for email: '{value}'`); anything else gives `Invalid 'sender': '{value}'`. Errors include `allowed_values.sender` keyed by ID as `Name `. Defaults on create (or when sent as `\"\"`) to the account's default sender.",
"examples": [
"boxoffice@example.org",
412,
"Box Office "
]
},
"reply_to": {
"type": [
"string",
"integer"
],
"description": "Same formats and resolution as `sender`; errors read `Invalid 'reply_to': '{value}'` and `No reply_to identity found for email: '{value}'`. No default. `\"\"` or `\"0\"` clears it.",
"examples": [
413
]
},
"language": {
"type": [
"string",
"integer"
],
"description": "`en` or `fr` (case-insensitive), or the IDs `1` (English) or `3` (French). `\"\"` or `\"0\"` sets `en`. Otherwise `Invalid 'language': '{value}'` with `allowed_values.language` `{\"1\":\"en\",\"3\":\"fr\"}`.",
"examples": [
"fr"
]
},
"recipient_subscription": {
"type": [
"string",
"integer"
],
"description": "Name or ID of a subscription, including the account's mandatory consent subscription (which sends the message as a mandatory, consent-exempt message, with the subscription's description as the stated reason). With a tag or segment, the subscription narrows it: only contacts in the tag or segment and subscribed are sent the message. Unknown: `Invalid 'recipient_subscription': '{value}'` with `allowed_values` when the account has 50 or fewer. On update, sending any one of the three recipient fields clears the other two unless they are in the same request; `{\"recipient_subscription\": \"\"}` clears all three.",
"examples": [
"Season News"
]
},
"recipient_tag": {
"type": [
"string",
"integer"
],
"description": "Name or ID of a tag. Not with `recipient_segment`: `Only one of the fields 'recipient_tag' or 'recipient_segment' may be provided`. Unknown: `Invalid 'recipient_tag': '{value}'`. Subject to the update rule described under `recipient_subscription`.",
"examples": [
"Cast Call"
]
},
"recipient_segment": {
"type": [
"string",
"integer"
],
"description": "Name or ID of a segment. Segments cannot be created through any API. Not with `recipient_tag`. Unknown: `Invalid 'recipient_segment': '{value}'`. Subject to the update rule described under `recipient_subscription`.",
"examples": [
"Lapsed Subscribers"
]
},
"recipient_language": {
"type": [
"string",
"integer"
],
"description": "`en`, `fr`, `1`, or `3`: send only to contacts with that language. `\"\"` or `\"0\"` clears it (all languages). Never cleared by the recipient update rule. Otherwise `Invalid 'recipient_language': '{value}'`.",
"examples": [
"en"
]
},
"publish_archive": {
"type": [
"boolean",
"string",
"integer"
],
"description": "`true`, `\"true\"`, `1`, `\"1\"`, `\"yes\"`, or `\"on\"` publishes the message to the web archive; anything else is `false`. Defaults to `false`.",
"examples": [
true
]
},
"utm_tag_links": {
"type": [
"boolean",
"string",
"integer"
],
"description": "Accepted values as for `publish_archive`. Defaults on create to `true` if link analytics is on in the account preferences, otherwise `false`.",
"examples": [
true
]
},
"send_time": {
"type": "string",
"description": "A future date and time, read as account-local wall-clock time, e.g. `2026-10-20 09:00:00`. An offset or `Z` is dropped and the remaining time is still read in the account time zone. Stored only: it does not schedule the message; it is used when the message is sent. A time in the past gives `The field 'send_time' must be in the future`; a value that is not a date gives `Invalid 'send_time': '{value}'`; `\"\"` or `null` is read as the current time and fails as not in the future, so `send_time` cannot be cleared.",
"examples": [
"2026-10-20 09:00:00"
]
},
"html": {
"type": "string",
"maxLength": 204800,
"description": "The complete message HTML, stored as sent without checks. Over 204,800 bytes fails with `The field 'html' may not be longer than 200kB`; the size is checked before `replace` is applied. `\"\"` counts as not sent, so content cannot be blanked. On update it replaces the whole content. HTML containing Envoke's `Spring Season
Four shows, one season pass.