Tag API - Add and Remove Contacts

Use these endpoints to assign contacts to a tag or remove them in bulk. Both operations are idempotent — adding a contact that is already tagged, or removing one that is not tagged, produces no error.

Endpoints

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

Replace {ID} with the Envoke tag 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 tag ID in the URL does not match any tag 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/tags/42/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/tags/42/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/tags/42/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/tags/42/contacts"

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

For code examples and interactive testing, visit api.envoke.com.