Menu

Contacts API - Recipients

Elements that can be shared among more than one endpoint definition.

Search recipients

POST /contactdb/recipients/search

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"
  • 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".

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Request Body

object
list_id
integer
format: int32
required
conditions
array[object]

The conditions by which this segment should be created.

required
field
string
value
string
operator
string
Allowed Values: eq, ne, lt, gt, contains
and_or
string
Allowed Values: and, or,
{
  "list_id": -27497588,
  "conditions": [
    {
      "and_or": "",
      "field": "birthday",
      "value": "01/12/1985",
      "operator": "eq"
    },
    {
      "and_or": "",
      "field": "birthday",
      "value": "01/12/1985",
      "operator": "eq"
    },
    {
      "and_or": "",
      "field": "birthday",
      "value": "01/12/1985",
      "operator": "eq"
    },
    {
      "and_or": "",
      "field": "birthday",
      "value": "01/12/1985",
      "operator": "eq"
    }
  ]
}

Responses

object
recipients
array[object]
created_at
integer
email
string
id
string
last_emailed
integer
last_clicked
integer
last_opened
integer
custom_fields
array[object]
id
integer
name
string
value
type
string
updated_at
integer
first_name
string
recipient_count
integer
No response body.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more