Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Get Contacts by Emails



API Overview

api-overview page anchor

POST/v3/marketing/contacts/search/emails

Base url: https://api.sendgrid.com

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 client side results.

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

authentication page anchor
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
SchemaExample
emailsarray[string]required

One or more primary and/or alternate email addresses to search for in your Marketing Campaigns contacts.


phone_number_idstring

The contact's Phone Number ID. This is required to be a valid phone number.


external_idstring

The contact's External ID.

Max length: 254

anonymous_idstring

The contact's Anonymous ID.

Max length: 254
200400401403404500

An object containing one or more of the email addresses matching the searched addresses in your contacts.

SchemaExample
resultobject

Get Contacts by Emails

get-contacts-by-emails page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_25
const client = require('@sendgrid/client');
_25
client.setApiKey(process.env.SENDGRID_API_KEY);
_25
_25
const data = {
_25
"emails": [
_25
"jane_doe@example.com",
_25
"john_doe@example.com",
_25
"joann_doe@example.com"
_25
]
_25
};
_25
_25
const request = {
_25
url: `/v3/marketing/contacts/search/emails`,
_25
method: 'POST',
_25
body: data
_25
}
_25
_25
client.request(request)
_25
.then(([response, body]) => {
_25
console.log(response.statusCode);
_25
console.log(response.body);
_25
})
_25
.catch(error => {
_25
console.error(error);
_25
});


Rate this page: