Menu

Contacts

Get Contacts by Emails

Get Contacts by Emails

POST /marketing/contacts/search/emails

This endpoint allows you to retrieve up to 100 contacts matching the searched email address(es), including any alternate_emails.

Email addresses are unique to a contact, meaning this endpoint can treat an email address as a primary key to search by. The contact object associated with the address, whether it is their email or one of their alternate_emails will be returned if matched.

Email addresses in the search request do not need to match the case in which they're stored, but the email addresses in the result will be all lower case. Empty strings are excluded from the search and will not be returned.

This endpoint should be used in place of the "Search Contacts" endpoint when you can provide exact email addresses and do not need to include other Segmentation Query Language (SGQL) filters when searching.

If you need to access a large percentage of your contacts, we recommend exporting your contacts with the "Export Contacts" endpoint and filtering the results client side.

This endpoint returns a 200 status code when any contacts match the address(es) you supplied. When searching multiple addresses in a single request, it is possible that some addresses will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the email address(es) that are not found.

This endpoint returns a 404 status code when no contacts are found for the provided email address(es).

A 400 status code is returned if any searched addresses are invalid.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Request Body

object
emails
array[string]

One or more primary emails and/or alternate emails to search through your contacts for.

required
{
  "emails": [
    "jane_doe@example.com",
    "john_doe@example.com",
    "joann_doe@example.com"
  ]
}

Responses

object
result
object
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string
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