Cakemail
Cakemail API

Filtering contacts with JSON

A JSON filter selects the contacts of a list that match conditions: a status, a tag, an interest, a custom attribute, a date, or what they did with your campaigns. The same filter works to list contacts, to export them, to tag them or set their interests in bulk, and to define a segment.

Where the filter goes

The filter is called json everywhere. It is a query parameter on requests that read or export contacts, and a body field on requests that change them.

RequestWhere json goes
Show contacts of a list: GET /lists/{list_id}/contactsquery parameter
Show contacts of a segment: GET /lists/{list_id}/segments/{segment_id}/contactsquery parameter, combined with the segment's own conditions
Create a contacts export: POST /lists/{list_id}/exportsquery parameter
Tag multiple contacts: POST /lists/{list_id}/contacts/tagbody field
Untag multiple contacts: POST /lists/{list_id}/contacts/untagbody field
Add interests to contacts: POST /lists/{list_id}/contacts/add-interestsbody field
Remove interests from contacts: POST /lists/{list_id}/contacts/remove-interestsbody field
Create a segment: POST /lists/{list_id}/segmentsbody field
Update a segment: PATCH /lists/{list_id}/segments/{segment_id}body field

The query and fiql parameters that these requests also accept are deprecated: use json. Send only one of the three in a request.

How a filter is built

A filter is a JSON object with exactly one key, the operator. The operator's value is the condition:

JSONCode
{"eq": {"status": "active"}}

To combine conditions, use and or or, whose value is a list of filters. Each item is itself a filter, so they nest:

JSONCode
{ "and": [ {"eq": {"status": "active"}}, {"tagged": {"tag": "vip"}}, {"or": [ {"eq": {"country": "CA"}}, {"eq": {"country": "FR"}} ]} ] }

This selects active contacts tagged vip whose country custom attribute is CA or FR.

An object with two keys is refused: write {"and": [{"eq": {"status": "active"}}, {"eq": {"country": "CA"}}]}, not {"eq": {"status": "active", "country": "CA"}}.

Attributes you can compare

The comparison and date operators take one {attribute: value} pair. The attribute is a column of the list:

  • email: the contact's email address.
  • status: the contact's status in the list, such as active or unsubscribed.
  • registered: the date and time the contact was added to the list. Responses call this date subscribed_on, but a filter must use registered.
  • id: the contact's ID.
  • Any custom attribute of the list, by its name, such as country or birthday.

Values are written as strings, numbers included: {"gt": {"age": "30"}}.

Operators

Compare an attribute

OperatorSelects contacts whose attribute…Example
eqequals the value{"eq": {"status": "active"}}
nediffers from the value{"ne": {"country": "CA"}}
gt, geis greater than, or greater than or equal to, the value{"gt": {"age": "30"}}
lt, leis less than, or less than or equal to, the value{"le": {"registered": "2026-01-01"}}
likematches the pattern, where * stands for any characters{"like": {"email": "*@example.com"}}
unlikedoesn't match the pattern{"unlike": {"email": "*@example.com"}}

Tags and interests

OperatorSelects contacts that…Example
taggedhave the tag{"tagged": {"tag": "vip"}}
nottaggeddon't have the tag{"nottagged": {"tag": "vip"}}
interestedhave the interest{"interested": {"interest": "sports"}}
notinteresteddon't have the interest{"notinterested": {"interest": "sports"}}

Dates relative to now

The value is "<n> <unit>", where the unit is year, month, week, day, hour, minute or second.

OperatorSelects contacts whose date attribute is…Example
less_than_time_agowithin the last <n> <unit>{"less_than_time_ago": {"registered": "30 day"}}
more_than_time_agoolder than <n> <unit>{"more_than_time_ago": {"registered": "1 year"}}
less_than_time_awayin the future, within the next <n> <unit>{"less_than_time_away": {"renewal_date": "1 week"}}
more_than_time_awayfurther in the future than <n> <unit>{"more_than_time_away": {"renewal_date": "1 month"}}

What contacts did with your campaigns

Each activity operator has a negative form with not in front: open and notopen, sent and notsent, clicked and notclicked, bounced and notbounced, unsubscribed and notunsubscribed, complained and notcomplained, engaged and notengaged, blocked and notblocked.

Its value names the campaigns, in one of three ways:

OperandMeansExample
campaignone campaign, by its ID{"open": {"campaign": "123"}}
mailings with PAST(<n> <unit>)the campaigns sent in that past period{"notopen": {"mailings": "PAST(6 month)"}}
mailings with <YYYY-MM-DD>,<YYYY-MM-DD>the campaigns sent between those dates{"bounced": {"mailings": "2026-01-01,2026-06-30"}}

clicked and notclicked also accept link, a link's ID: {"clicked": {"link": "456"}}.

mailings takes only a past period or a date range: FUTURE(...) is refused.

Send a filter in a query parameter

In a GET, and in POST /lists/{list_id}/exports, the filter is a JSON string in the json query parameter, URL-encoded. Let your HTTP client do the encoding.

This lists the active contacts tagged vip:

TerminalCode
curl --get \ --url "https://api.cakemail.dev/lists/[list id]/contacts" \ --header 'accept: application/json' \ --header 'authorization: Bearer [access token]' \ --data-urlencode 'json={"and":[{"eq":{"status":"active"}},{"tagged":{"tag":"vip"}}]}'
Code
import json import requests url = f"https://api.cakemail.dev/lists/{list_id}/contacts" json_filter = {"and": [{"eq": {"status": "active"}}, {"tagged": {"tag": "vip"}}]} headers = { "accept": "application/json", "authorization": f"Bearer {token}" } response = requests.get(url, params={"json": json.dumps(json_filter)}, headers=headers) print(response.text)
PHPCode
<?php require_once('vendor/autoload.php'); $client = new \GuzzleHttp\Client(); $filter = ['and' => [ ['eq' => ['status' => 'active']], ['tagged' => ['tag' => 'vip']], ]]; $response = $client->request('GET', "https://api.cakemail.dev/lists/{$listId}/contacts", [ 'query' => ['json' => json_encode($filter)], 'headers' => [ 'accept' => 'application/json', 'authorization' => "Bearer {$token}" ], ]); echo $response->getBody();

On a segment, the filter narrows the segment: GET /lists/{list_id}/segments/{segment_id}/contacts?json=... returns the segment's contacts that also match the filter.

Send a filter in a request body

In the bulk requests and the segment requests, json is a field of the JSON body, written as an object, not as a string.

This tags as inactive every contact that opened none of the campaigns of the last six months:

TerminalCode
curl --request POST \ --url "https://api.cakemail.dev/lists/[list id]/contacts/tag" \ --header 'accept: application/json' \ --header 'authorization: Bearer [access token]' \ --header 'content-type: application/json' \ --data '{"tags":["inactive"],"json":{"notopen":{"mailings":"PAST(6 month)"}}}'

This creates a segment of the contacts added in the last 30 days:

TerminalCode
curl --request POST \ --url "https://api.cakemail.dev/lists/[list id]/segments" \ --header 'accept: application/json' \ --header 'authorization: Bearer [access token]' \ --header 'content-type: application/json' \ --data '{"name":"New this month","json":{"less_than_time_ago":{"registered":"30 day"}}}'

In the tag, untag and interest requests, send either contact_ids or a filter, not both.

When a filter is refused

A filter that can't be read is answered with 400 Bad Request. The message says what is wrong:

  • Invalid condition: an object holds more than one key.
  • Invalid operator: <name>: the operator doesn't exist.
  • Invalid attribute `<name>` for operator `<operator>`: the attribute doesn't go with this operator, for example mailings with eq, or link with open.
  • Invalid link id `<value>`: a link isn't a positive whole number.
  • Invalid JSON expression: any other problem, such as a date value that isn't "<n> <unit>" or a mailings value with FUTURE(...).

A request that sends more than one of query, fiql and json is refused too.

The full grammar is in the API reference, under the json parameter of each request listed above.

Last modified on