Get a contact's consent state

GET

/api/v3/contacts/{email}/consents

const url = 'https://api.tryletterhead.com/api/v3/contacts/example/consents?api=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Returns a contact’s full notification consent state on its own, without the rest of the contact profile — the same three sections carried on the full contact response (GET /api/v3/contacts/{email}), assembled here for a caller that only needs consent data: endpoints (the address registry — masked addresses, verification and invalidation timestamps), channelConsents (channel-scoped opt-ins), and consents (medium-level revocations, channel: null for a company-wide one).

This read is deliberately unrestricted — it’s available regardless of whether notification-platform writes are enabled for your tenant.

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

Authorizations

bearerAuth

Parameters

Path Parameters

email

required

string

The contact’s email address, URL-encoded.

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

application/json

object

items

object

endpoints

Array<object>

object

medium

string

address

Masked — the leading + and first two digits, elided middle digits, last two digits.

string

countryCode

string

verifiedAt

string

nullable

invalidatedAt

string

nullable

source

string

createdAt

string

updatedAt

string

channelConsents

Array<object>

object

channel

string

medium

string

status

string

method

string

occurredAt

string

consents

Array<object>

object

channel

Null for a company-wide revocation.

string

nullable

medium

string

status

string

method

string

source

string

nullable

occurredAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": {
    "endpoints": [
      {
        "medium": "sms",
        "address": "+1•••••••00",
        "countryCode": "US",
        "verifiedAt": "2026-06-01T12:00:00+00:00",
        "invalidatedAt": null,
        "source": "manual",
        "createdAt": "2026-06-01T12:00:00+00:00",
        "updatedAt": "2026-06-01T12:00:00+00:00"
      }
    ],
    "channelConsents": [
      {
        "channel": "weekly-digest",
        "medium": "sms",
        "status": "opted_in",
        "method": "double_opt_in",
        "occurredAt": "2026-06-01T12:00:00+00:00"
      }
    ],
    "consents": []
  },
  "message": "Consent state retrieved.",
  "total": 1
}

Still can’t find what you need? Contact support.