Apply tags to contacts matching a filter snapshot

POST

/api/v3/contacts/tags/matching

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 ] }'

• Production

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, plus an optional emails 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

• bearerAuth

Request Body ^required

Media type application/json

object

api

required

Required. Set to true to authenticate with an API key.

boolean

tagsToApply

required

1 or more tag names to apply.

Array<string>

query

string

channels

Array<integer>

statuses

Array<integer>

tags

Filter to contacts already carrying these tags (not to be confused with tagsToApply).

Array<string>

untagged

boolean

emails

Optional allow-list — when present, only these emails (still narrowed by any other filters) are tagged.

Array<string>

Example

{
  "api": true,
  "tagsToApply": [
    "engaged-readers"
  ],
  "query": "newsletter fan",
  "statuses": [
    1
  ]
}

Responses

200

200 OK

Media type application/json

object

items

object

matched

Contacts matching the filter.

integer

updated

Contacts the tags were actually added to.

integer

message

string

total

integer

Example

{
  "items": {
    "matched": 340,
    "updated": 312
  },
  "message": "Tags applied to matching contacts.",
  "total": 312
}