POST /contacts/v1/addresses/email/search

Retrieve the contact key for one or more email addresses. This resource is helpful for situations where you need to find a contact key that’s different from the channel address.

Properties

The JSON request body contains these properties.

Name	Type	Description
`channelAddressList`	Array	Required. An array of strings. Each string in the array is an email address to find the contact key for.
`maximumCount`	Integer	The maximum number of contact keys to return for each email address. The default value is `1`.

Response Properties

A successful request returns a 200 OK result. The response contains the properties described in this table.

Name	Type	Description
`channelAddressResponseEntities`	Array	An array of objects that contain contact key details for an email address.
`requestServiceMessageID`	String	A unique ID for the request.
`responseDateTime`	Datetime	The date and time when the API generated the response.
`resultMessages`	Array	An array of objects that contains messages generated while processing the request. The array is typically empty in a successful request.
`serviceMessageID`	String	A unique ID for the response.

Objects in the channelAddressResponseEntities Array

Each object in the channelAddressResponseEntities array has the properties described in this table.

Name	Type	Description
`channelAddress`	String	The email address specified in the request.
`contactKeyDetails`	Array	An array of objects that contain information about a contact key. If there aren’t any contact key matches for a specified email address, the array contains an empty object.

Objects in the contactKeyDetails Array

Each object in the contactKeyDetails array has the properties described in this table.

Name	Type	Description
`contactKey`	String	The contact key associated with the email address.
`createDate`	Datetime	The date and time when the contact key was created.

Objects in the resultMessages Array

In a successful request, the resultMessages array is typically empty. If an error occurs, the objects in the array have the properties described in this table.

Name	Type	Description
`message`	String	A message that explains the error that occurred.
`resultClass`	String	A description of the result. If an error occurs, the value is `Error`.
`resultCode`	String	An error code.
`resultType`	String	A description of the type of result.

Usage

To retrieve contact keys for an email address, issue a POST request to the /contacts/v1/addresses/email/search endpoint. In the JSON request body, specify the email addresses to retrieve contact keys for.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/addresses/email/search
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "ChannelAddressList": [
    "dangelo.cunningham@example.com"
  ],
  "MaximumCount": 1
}

The response includes the contact keys for the specified email address.

{
  "channelAddressResponseEntities": [
    {
      "contactKeyDetails": [
        {
          "contactKey": "5cdc4716-c273-4eec-aacf-8e668a01ecbf",
          "createDate": "2025-11-15T11:51:00"
        }
      ],
      "channelAddress": "dangelo.cunningham@example.com"
    }
  ],
  "requestServiceMessageID": "35921326-7074-4cf9-8233-f61e76de0054",
  "responseDateTime": "2025-06-13T16:55:21.2506991-06:00",
  "resultMessages": [],
  "serviceMessageID": "cba1b474-6868-4611-99c3-ea0211e7bc36"
}