On this page

Search recipients

API Overview

(warning)

Legacy Marketing Campaigns

You are viewing the Legacy Marketing Campaigns API reference. For guidance migrating to the current version of Marketing Campaigns, see Migrating from Legacy Marketing Campaigns

(information)

Info

For the most up-to-date information on the Contacts API, please visit the new Marketing Campaigns Contacts API.

The Contacts Recipients API allows you to manage your recipients. You can add, retrieve, update, and delete recipients, as well as get a count of all recipients and all billable recipients.

Operation overview

POST/v3/contactdb/recipients/search

Base url: https://api.sendgrid.com (The Twilio SendGrid v3 API)

Search using segment conditions without actually creating a segment. Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on.

Valid operators for create and update depend on the type of the field for which you are searching.

Dates:
- "eq", "ne", "lt" (before), "gt" (after)
  - You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
- "empty", "not_empty"
- "is within"
  - You may use an ISO 8601 date format or the # of days.
Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value), "empty", "not_empty"
Numbers: "eq", "lt", "gt", "empty", "not_empty"
Email Clicks and Opens: "eq" (opened), "ne" (not opened)

Field values must all be a string.

Search conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either clicks.campaign_identifier or opens.campaign_identifier.

The condition value should be a string containing the id of a completed campaign.

Search conditions list may contain multiple conditions, joined by an "and" or "or" in the "and_or" field.

The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or".

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstringrequired

Default: Bearer <<YOUR_API_KEY_HERE>>

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredDescriptionChild properties

list_idinteger<int32>required

conditionsarray[object]required

The conditions by which this segment should be created.

Show child properties for conditions

Responses

200400

SchemaExample

Property nameTypeRequiredDescriptionChild properties

recipientsarray[object]

Show child properties for recipients

recipient_countinteger

Search recipients

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const data = {
5  list_id: -27497588,
6  conditions: [
7    {
8      and_or: "",
9      field: "birthday",
10      value: "01/12/1985",
11      operator: "eq",
12    },
13    {
14      and_or: "",
15      field: "birthday",
16      value: "01/12/1985",
17      operator: "eq",
18    },
19    {
20      and_or: "",
21      field: "birthday",
22      value: "01/12/1985",
23      operator: "eq",
24    },
25    {
26      and_or: "",
27      field: "birthday",
28      value: "01/12/1985",
29      operator: "eq",
30    },
31  ],
32};
33
34const request = {
35  url: `/v3/contactdb/recipients/search`,
36  method: "POST",
37  body: data,
38};
39
40client
41  .request(request)
42  .then(([response, body]) => {
43    console.log(response.statusCode);
44    console.log(response.body);
45  })
46  .catch((error) => {
47    console.error(error);
48  });