Get a contact

GET

/api/v3/contacts/{email}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/example?api=true' \
  --header 'Authorization: Bearer <token>'

• Production

Returns a single company-level contact’s full profile — name, tags, custom fields, notification endpoints and consents, subscriptions, and the segments they currently belong to.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Channel-scoped reads

Pass channel (a channel slug) to narrow the response to one newsletter: segments lists only the segments available on that channel instead of every segment in the company, and the request returns 404 if the contact has no subscription on the named channel. channel also returns 404 if the slug doesn’t match any channel in your company, or 403 if it names a channel another company owns. Omit channel for the company-wide view, which always returns the contact if they exist.

Authorizations

• bearerAuth

Parameters

Path Parameters

email

required

string

The contact’s email address, URL-encoded.

Query Parameters

api

required

boolean

Required. Set to true.

channel

string

Narrow the response to a single newsletter, by channel slug. Returns 404 if the contact has no subscription on that channel, if the slug doesn’t match a channel in your company, or 403 if it names another company’s channel. Omit for the company-wide view.

Responses

200

200 OK

Media type application/json

object

items

object

email

string

firstName

string

lastName

string

tags

Array<string>

customFields

object

__lh.engagementRefreshedAt

string

__lh.mailboxProvider

string

__lh.roleAddress

boolean

referralSource

string

lastOpenDate

string

optInTime

string

endpoints

Array<object>

object

channelConsents

Array<object>

object

consents

Array<object>

object

createdAt

string

updatedAt

string

subscriptions

Array<object>

object

channel

object

slug

string

name

string

status

integer

createdAt

string

updatedAt

string

segments

Array<object>

object

id

integer

name

string

message

string

total

integer

Example

{
  "items": {
    "email": "[email protected]",
    "firstName": "Avery",
    "lastName": "Chen",
    "tags": [
      "the-north",
      "engaged-readers"
    ],
    "customFields": {
      "__lh.engagementRefreshedAt": "2026-06-14T04:20:28+00:00",
      "__lh.mailboxProvider": "gmail",
      "__lh.roleAddress": false,
      "referralSource": "Embedded subscription box",
      "lastOpenDate": "2026-06-12 12:06:53",
      "optInTime": "2026-04-30 03:30:30"
    },
    "endpoints": [],
    "channelConsents": [],
    "consents": [],
    "createdAt": "2026-04-30T15:01:21+00:00",
    "updatedAt": "2026-06-13T13:05:04+00:00",
    "subscriptions": [
      {
        "channel": {
          "slug": "the-daily",
          "name": "The Daily"
        },
        "status": 1,
        "createdAt": "2026-04-30T15:22:41+00:00",
        "updatedAt": "2026-06-12T20:43:14+00:00"
      },
      {
        "channel": {
          "slug": "weekend-reads",
          "name": "Weekend Reads"
        },
        "status": 1,
        "createdAt": "2026-05-30T16:14:45+00:00",
        "updatedAt": "2026-05-30T16:14:45+00:00"
      }
    ],
    "segments": [
      {
        "id": 1,
        "name": "Highly engaged readers"
      }
    ]
  },
  "message": "Contact retrieved.",
  "total": 1
}

404

Either the contact has no subscription on the channel named by channel, or the slug doesn’t match a channel in your company.

Media type application/json

object

items

Array<object>

object

message

string

total

integer

Example ^generated

{
  "items": [
    {}
  ],
  "message": "example",
  "total": 1
}