Menu

Contacts API - Recipients

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

Search recipients

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[]
required
{
  "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.

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.