Get Contact

Retrieve a specific contact by UUID, including associated lists and custom fields, plus its subscription, deliverability, and engagement details.

Request

GET /contacts/{uuid}

Path Parameters

Parameter	Type	Description
uuid	string	Contact's UUID

Example Request

curl -X GET "https://email.easy.tools/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

Success Response (200 OK)

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+48123456789",
    "external_id": "customer_123",
    "language": "en",
    "country_code": "US",
    "timezone": {
      "uuid": "748ff067-d041-4a2f-a7ad-a6f7ce049cdf",
      "iana": "Europe/Warsaw",
      "region": "Europe",
      "city": "Warsaw"
    },
    "lists": [
      {
        "uuid": "a3f1c5d2-7e84-4b9f-8c63-1d0e2f3a4b5c",
        "name": "Newsletter"
      }
    ],
    "custom_fields": [
      {
        "field_key": "company",
        "value": "Acme Inc"
      },
      {
        "field_key": "events-attended",
        "value": ["Webinar X", "Webinar Y"]
      }
    ],
    "status": "subscribed",
    "subscription": {
      "is_unsubscribed": false,
      "unsubscribed_at": null
    },
    "deliverability": {
      "is_suppressed": false,
      "suppressed_at": null,
      "is_bounced": true,
      "last_bounce_type": "soft",
      "last_bounced_at": "2026-06-01T09:12:00Z",
      "is_complained": false,
      "last_complained_at": null
    },
    "engagement": {
      "last_sent_at": "2026-06-20T08:00:00Z",
      "last_opened_at": "2026-06-21T19:03:00Z",
      "last_clicked_at": null
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
uuid	string	Contact's unique identifier
email	string	Contact's email address
first_name	string|null	Contact's first name
last_name	string|null	Contact's last name
phone	string|null	Contact's phone number
external_id	string|null	External identifier for integration purposes
language	string|null	ISO 639-1 language code
country_code	string|null	ISO 3166-1 alpha-2 country code
timezone	object|null	Contact's assigned timezone as { uuid, iana, region, city }, or null when no timezone is set. See Timezones. The lean List Contacts rows do not include this object — read it here.
lists	array	Lists the contact belongs to
custom_fields	array	Custom field values for this contact. Each entry has field_key and value; list fields return value as an array of strings.
status	string	Headline subscription status: subscribed, unsubscribed, or suppressed.
subscription	object	Consent details (see below).
deliverability	object	Deliverability details (see below).
engagement	object	Most recent engagement timestamps (see below).
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

Status, subscription, deliverability & engagement

status is the headline subscription state. subscribed means the contact can receive mail; unsubscribed means they opted out; suppressed means they are undeliverable. When more than one applies, the most final state is reported, in the order suppressed → unsubscribed → subscribed. The subscription and deliverability objects carry the complete picture — consent and deliverability are independent, so a contact can be mailable yet unsubscribed, or undeliverable yet never have opted out. A contact that had a temporary bounce but is still mailable reads status: "subscribed" with is_bounced: true and is_suppressed: false.

Field	Type	Description
subscription.is_unsubscribed	boolean	Whether the contact has opted out of all mail.
subscription.unsubscribed_at	string|null	When the contact opted out (ISO 8601 UTC), or null.
deliverability.is_suppressed	boolean	Whether the contact is undeliverable and held back from sending.
deliverability.suppressed_at	string|null	When the contact became undeliverable (ISO 8601 UTC), or null.
deliverability.is_bounced	boolean	Whether the contact's most recent delivery attempt bounced.
deliverability.last_bounce_type	string|null	hard (permanent failure, which also makes the contact undeliverable) or soft (temporary failure that leaves the contact mailable), or null.
deliverability.last_bounced_at	string|null	When the most recent bounce happened (ISO 8601 UTC), or null.
deliverability.is_complained	boolean	Whether the contact has ever reported mail as spam.
deliverability.last_complained_at	string|null	When the contact last reported a complaint (ISO 8601 UTC), or null.
engagement.last_sent_at	string|null	When mail was last sent to the contact (ISO 8601 UTC), or null.
engagement.last_opened_at	string|null	When the contact last opened mail (ISO 8601 UTC), or null.
engagement.last_clicked_at	string|null	When the contact last clicked a link in mail (ISO 8601 UTC), or null.

Error Responses

Not Found Error (404)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact with UUID '550e8400-e29b-41d4-a716-446655440000' not found"
  }
}