Subscription API - Add and Remove Contacts

Use these endpoints to subscribe contacts to a subscription or unsubscribe them in bulk. Both operations are idempotent — adding a contact that is already subscribed, or removing one that is not subscribed, produces no error.

---

Endpoints

Method	URL	Description
POST	https://e1.envoke.com/v2/subscriptions/{ID}/contacts	Add contacts to a subscription.
DELETE	https://e1.envoke.com/v2/subscriptions/{ID}/contacts	Remove contacts from a subscription.

Replace {ID} with the Envoke subscription ID. Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

Request Body

Provide exactly one of contact_ids or contact_emails. You cannot include both in the same request.

Field	Type	Description
contact_ids	array of integers	Envoke contact IDs to add or remove. Maximum 1,000 items per request.
contact_emails	array of strings	Contact email addresses to add or remove. Maximum 1,000 items per request.

---

Response

Success (all contacts found)

{
  "success": true,
  "result_text": "Set to contacts",
  "result_data": {
    "processed": 3
  }
}

Success (some contacts not found)

Contacts that could not be matched are listed in not_found. The operation is still considered successful as long as no found contacts failed to update.

{
  "success": true,
  "result_text": "Set to contacts. Some contacts not found",
  "result_data": {
    "processed": 3,
    "not_found": ["ghost@example.com"]
  }
}

Failure

If one or more found contacts failed during the update, success is false and the failures are listed in failed.

{
  "success": false,
  "result_text": "Error setting to contacts",
  "result_data": {
    "processed": 3,
    "failed": [
      { "contact_id": "456", "reason": "error message" }
    ]
  }
}

result_data fields

Field	Type	Description
processed	integer	Total number of input identifiers submitted (found + not found).
not_found	array	IDs or emails that were not matched to any contact in the account. Only present when at least one was not found.
failed	array	Contacts that were found but failed during the update. Only present when failures occurred.

---

Validation Errors

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Either 'contact_ids' or 'contact_emails' must be provided"]
  }
}

If the request body is completely empty ({}), a validation envelope is returned:

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": ["Request body may not be empty"]
  }
}

Common validation errors (returned when a non-empty body is provided but is missing or invalid):

Error	Cause
Either 'contact_ids' or 'contact_emails' must be provided	Body was provided but contained neither field.
Provide either 'contact_ids' or 'contact_emails', not both	Both fields were included.
The field 'contact_ids' must be an array	contact_ids was not an array.
The field 'contact_ids' must not be empty	contact_ids was an empty array.
The field 'contact_ids' may not contain more than 1000 items	More than 1,000 IDs were submitted.
The field 'contact_emails' must be an array	contact_emails was not an array.
The field 'contact_emails' must not be empty	contact_emails was an empty array.
The field 'contact_emails' may not contain more than 1000 items	More than 1,000 emails were submitted.
Item with id '{id}' not found	The subscription ID in the URL does not match any subscription in your account.

---

Examples

Add contacts by ID

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [101, 102, 103]}' \
  "https://e1.envoke.com/v2/subscriptions/12/contacts"

Add contacts by email

curl -X POST -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_emails": ["alice@example.com", "bob@example.com"]}' \
  "https://e1.envoke.com/v2/subscriptions/12/contacts"

Remove contacts by ID

curl -X DELETE -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [101, 102]}' \
  "https://e1.envoke.com/v2/subscriptions/12/contacts"

Remove contacts by email

curl -X DELETE -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_emails": ["alice@example.com"]}' \
  "https://e1.envoke.com/v2/subscriptions/12/contacts"

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

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