Apply tags to contacts matching a filter snapshot
const url = 'https://api.tryletterhead.com/api/v3/contacts/tags/matching';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"api":true,"tagsToApply":["engaged-readers"],"query":"newsletter fan","statuses":[1]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tryletterhead.com/api/v3/contacts/tags/matching \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "api": true, "tagsToApply": [ "engaged-readers" ], "query": "newsletter fan", "statuses": [ 1 ] }'Bulk-applies one or more tags to every contact matching a browse-filter snapshot — the same filter shape Search contacts and List/browse contacts accept (query, channels, statuses, tags, untagged, customFields, segmentId, a created-date window, hasEmail/hasPhone presence filters, plus an optional emails/contactKeys allow-list to target a hand-picked subset instead of a full-scan match). Any filter shape is accepted, including no filters at all — which targets your entire audience — so build the request from whichever narrowing fields you need.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Required. Set to true to authenticate with an API key.
1 or more tag names to apply.
Filter to contacts already carrying these tags (not to be confused with tagsToApply).
Optional allow-list — when present, only these emails (still narrowed by any other filters) are tagged.
Optional contact-key allow-list — the email-less counterpart to emails, for the same “selected rows” path, carrying opaque 64-character hex contact keys so an endpoint-anchored (phone-only) contact can be in a hand-picked selection. Unions with emails.
Restrict the match to contacts that do (true) or don’t (false) have an email address. Omit for no constraint.
Restrict the match to contacts that do (true) or don’t (false) have an active messaging endpoint. hasPhone=true combined with hasEmail=false is the SMS-only cohort. Omit for no constraint.
Example
{ "api": true, "tagsToApply": [ "engaged-readers" ], "query": "newsletter fan", "statuses": [ 1 ]}Responses
Section titled “ Responses ”200 OK
object
object
Contacts matching the filter.
Contacts the tags were actually added to.
Example
{ "items": { "matched": 340, "updated": 312 }, "message": "Tags applied to matching contacts.", "total": 312}Still can’t find what you need? Contact support.