GET /api/contacts/{id}/history — Contact Email History

GET /api/contacts/{contact_id}/history gives your application a full scoped view of a contact’s email activity: every campaign they were included in, every transactional message sent to them, and every email event attached to their contact record. Results are scoped to the authenticated client’s audience so that one client cannot read another client’s send history for the same contact.

Endpoint

GET /api/contacts/{contact_id}/history

Authentication

Requires a Bearer token for the client whose slug is passed as the client query parameter.

Authorization: Bearer <client-api-key>

Path parameters

contact_id

integer

required

The internal Datamailer contact ID. Must be a contact that has a client-scoped subscription record in the specified audience.

Query parameters

audience

string

required

Slug of the audience to scope campaign recipient history to.

client

string

required

Slug of the authenticated client. Scopes both campaign and transactional history.

limit

integer

default:"50"

Maximum number of email events to return per page. Must be between 1 and 100. Campaign recipients and transactional messages are also independently capped at limit rows — they are not paginated separately.

cursor

integer

Email event ID to paginate from. Pass the value of next_cursor from the previous response to retrieve the next page of events. Omit for the first page.

Response

contact_id

integer

Internal Datamailer contact ID.

string

Normalized (lowercased) email address of the contact.

audience

string

Slug of the audience the history is scoped to.

client

string

Slug of the client the history is scoped to.

campaign_recipients

object[]

Campaign recipient records for this contact in campaigns belonging to the specified audience and client, ordered by created_at descending. Capped at limit rows.

Show campaign_recipients item fields

type

string

Always "campaign_recipient".

integer

Internal campaign recipient ID.

created_at

string

ISO-8601 UTC timestamp when the recipient record was created.

campaign

object

Summary of the campaign this recipient belongs to.

Show campaign fields

integer

Campaign ID.

subject

string

Campaign subject line.

audience

string

Audience slug.

client

string

Client slug.

string

Email address used for this send attempt.

status

string

One of pending, sent, skipped, failed, bounced, complained, unsubscribed.

skip_reason

string | null

Set when status is skipped. One of unverified, invalid_email, global_unsubscribe, client_unsubscribe, audience_unsubscribe, hard_bounce, complaint, duplicate, suppressed.

sent_at

string | null

ISO-8601 UTC timestamp when the message was sent, or null.

delivered_at

string | null

ISO-8601 UTC timestamp of confirmed delivery, or null.

first_opened_at

string | null

ISO-8601 UTC timestamp of first open event, or null.

first_clicked_at

string | null

ISO-8601 UTC timestamp of first click event, or null.

open_count

integer

Total number of open events recorded.

click_count

integer

Total number of click events recorded.

last_error

string

Last delivery error message, or an empty string.

transactional_messages

object[]

Transactional messages sent to this contact by the authenticated client, ordered by created_at descending. Capped at limit rows. Not audience-scoped — includes all transactional sends from this client to this contact.

Show transactional_messages item fields

type

string

Always "transactional_message".

integer

Internal transactional message ID.

created_at

string

ISO-8601 UTC timestamp when the message was created.

client

string

Client slug.

string

Recipient email address used for this send.

template_key

string

Key of the email template used.

status

string

One of queued, sent, failed, skipped, bounced, complained.

subject

string

Rendered subject line of the message.

sent_at

string | null

ISO-8601 UTC timestamp when the message was sent, or null.

delivered_at

string | null

ISO-8601 UTC timestamp of confirmed delivery, or null.

first_opened_at

string | null

ISO-8601 UTC timestamp of first open event, or null.

first_clicked_at

string | null

ISO-8601 UTC timestamp of first click event, or null.

open_count

integer

Total number of open events recorded.

click_count

integer

Total number of click events recorded.

last_error

string

Last delivery error message, or an empty string.

events

object[]

Email events for this contact scoped to the client and audience, ordered by event id descending. Paginated via cursor and next_cursor.

Show events item fields

type

string

Always "email_event".

integer

Internal email event ID. Use as cursor value for the next page.

created_at

string

ISO-8601 UTC timestamp when the event was recorded.

event_type

string

One of queued, skipped, sent, delivered, open, click, unsubscribe, bounce, complaint, failed.

client

string | null

Client slug, or null for events not attached to a client.

audience

string | null

Audience slug, or null for events not attached to an audience.

campaign_id

integer | null

Associated campaign ID, or null.

campaign_recipient_id

integer | null

Associated campaign recipient ID, or null.

transactional_message_id

integer | null

Associated transactional message ID, or null.

metadata

object

Safe subset of event metadata. May include keys: reason, error, scope, ses_message_id, bounce_type, complaint_feedback_type, source. Empty values and keys outside this allowlist are omitted.

next_cursor

string | null

The event ID to pass as the cursor query parameter to retrieve the next page of events. null when there are no further pages.

Example

Request

curl "https://datamailer.example.com/api/contacts/42/history?audience=dtc-courses&client=dtc-courses&limit=25" \
  -H "Authorization: Bearer dm_dtccourses_demo_transactional_email_key"

Response

{
  "contact_id": 42,
  "email": "learner@example.com",
  "audience": "dtc-courses",
  "client": "dtc-courses",
  "campaign_recipients": [
    {
      "type": "campaign_recipient",
      "id": 1001,
      "created_at": "2024-09-10T08:00:00Z",
      "campaign": {
        "id": 7,
        "subject": "ML Zoomcamp — Week 2 kickoff",
        "audience": "dtc-courses",
        "client": "dtc-courses"
      },
      "email": "learner@example.com",
      "status": "sent",
      "skip_reason": null,
      "sent_at": "2024-09-10T08:05:00Z",
      "delivered_at": "2024-09-10T08:05:12Z",
      "first_opened_at": "2024-09-10T09:14:00Z",
      "first_clicked_at": null,
      "open_count": 2,
      "click_count": 0,
      "last_error": ""
    }
  ],
  "transactional_messages": [
    {
      "type": "transactional_message",
      "id": 305,
      "created_at": "2024-09-01T10:00:00Z",
      "client": "dtc-courses",
      "email": "learner@example.com",
      "template_key": "registration-welcome",
      "status": "sent",
      "subject": "Welcome to ML Zoomcamp!",
      "sent_at": "2024-09-01T10:00:05Z",
      "delivered_at": "2024-09-01T10:00:18Z",
      "first_opened_at": "2024-09-01T10:30:00Z",
      "first_clicked_at": "2024-09-01T10:31:45Z",
      "open_count": 3,
      "click_count": 1,
      "last_error": ""
    }
  ],
  "events": [
    {
      "type": "email_event",
      "id": 8842,
      "created_at": "2024-09-10T09:14:00Z",
      "event_type": "open",
      "client": "dtc-courses",
      "audience": "dtc-courses",
      "campaign_id": 7,
      "campaign_recipient_id": 1001,
      "transactional_message_id": null,
      "metadata": {}
    },
    {
      "type": "email_event",
      "id": 8101,
      "created_at": "2024-09-01T10:31:45Z",
      "event_type": "click",
      "client": "dtc-courses",
      "audience": null,
      "campaign_id": null,
      "campaign_recipient_id": null,
      "transactional_message_id": 305,
      "metadata": {}
    }
  ],
  "next_cursor": null
}

Paginating events

Pass next_cursor as the cursor parameter on the next request to retrieve older events:

curl "https://datamailer.example.com/api/contacts/42/history?audience=dtc-courses&client=dtc-courses&limit=25&cursor=8101" \
  -H "Authorization: Bearer dm_dtccourses_demo_transactional_email_key"

Privacy: secret tracking tokens, unsubscribe token hashes, and delivery link tokens stored on CampaignRecipient and TransactionalMessage records are never included in the history response. Only safe display fields are returned.

Scope: campaign_recipients is filtered to campaigns whose audience and client match the query parameters. transactional_messages is filtered by client only — transactional sends are not audience-scoped. events includes events where client matches or is null, and audience matches or is null, keeping provider webhook events (which may lack audience context) visible.

Error codes

Field	Error code	Meaning
`contact_id`	`not_found`	No contact with that ID, or no client subscription in this audience. Returns HTTP `404`.
`audience`	`required`	`audience` was missing or blank.
`audience`	`not_found`	No audience with that slug in the client’s organization.
`client`	`required`	`client` was missing or blank.
`client`	`forbidden`	`client` does not match the authenticated client. Returns HTTP `403`.
`limit`	`must_be_integer`	`limit` query parameter could not be parsed as an integer.
`limit`	`must_be_between_1_and_100`	`limit` is outside the allowed range of 1–100.
`cursor`	`must_be_integer`	`cursor` query parameter could not be parsed as an integer.
`cursor`	`must_be_positive`	`cursor` is less than 1.

Overview

Contacts

Subscriptions

Import & Export

Transactional

GET /api/contacts/{id}/history — Contact Email History

Endpoint

Authentication

Path parameters

Query parameters

Response

Example

Request

Response

Paginating events

Error codes

Build docs developers (and LLMs) love

Overview

Contacts

Subscriptions

Import & Export

Transactional

Documentation Index

​Endpoint

​Authentication

​Path parameters

​Query parameters

​Response

​Example

​Request

​Response

​Paginating events

​Error codes

Build docs developers (and LLMs) love

Endpoint

Authentication

Path parameters

Query parameters

Response

Example

Request

Response

Paginating events

Error codes