Lumail
Sign up

Get Subscriber Events

Retrieve the event history for a specific subscriber

MethodGET
/api/v1/subscribers/{subscriber}/events

https://lumail.io/api/v1/subscribers/{subscriber}/events

Retrieves the event history for a specific subscriber. This endpoint supports cursor-based pagination, filtering by event type, and date range filtering.

Query Parameters

ParameterTypeDefaultDescription
cursorstring-Base64-encoded cursor for pagination
takenumber20Number of events to return (1-100)
eventTypesstring-JSON array of event types to filter (e.g. ["EMAIL_OPENED"])
orderstring"desc"Sort order by createdAt ("asc" or "desc")
startDatestring-ISO 8601 datetime to filter events after this date
endDatestring-ISO 8601 datetime to filter events before this date
searchstring-Search query to filter events by data content or subscriber

Response

  • Success (200 OK) - Returns the events array with pagination cursor.
  • Error (404 Not Found) - Returned if the subscriber does not exist.

Response Fields

FieldTypeDescription
eventsarrayArray of event objects
events[].idstringUnique identifier for the event
events[].eventTypestringType of the event (see supported types below)
events[].dataobjectEvent-specific data payload
events[].subscriberIdstringID of the subscriber
events[].createdAtstringISO timestamp when the event occurred
events[].subscriberobjectSubscriber details
events[].subscriber.idstringSubscriber ID
events[].subscriber.emailstringSubscriber email
events[].subscriber.namestring/nullSubscriber name
nextCursorstring/nullCursor for the next page (null if no more pages)

Supported Event Types

Email Engagement Events

Event TypeDescriptionData Fields
EMAIL_SENTEmail was sent to subscriberemailId, campaignId, subject, workflow?
EMAIL_RECEIVEDEmail was successfully deliveredemailId, campaignId, subject, receivedAt?
EMAIL_OPENEDSubscriber opened an emailemailId, campaignId?, subject
EMAIL_CLICKEDSubscriber clicked a link in an emailemailId, campaignId?, subject, targetUrl, linkId?
EMAIL_BOUNCEDEmail could not be deliveredemailId, campaignId?, subject, reason, bounceType
EMAIL_COMPLAINEDSubscriber marked email as spamemailId, campaignId?, subject
EMAIL_DELIVERY_DELAYEDEmail delivery was temporarily delayedemailId, campaignId?, subject, workflow?

Subscription Events

Event TypeDescriptionData Fields
SUBSCRIBEDSubscriber joined your listtags? (array of tag objects)
UNSUBSCRIBEDSubscriber opted outreason?, campaignId?, campaignName?, status?

Tag Events

Event TypeDescriptionData Fields
TAG_ADDEDTag was applied to subscribertagId, tagName, reason?
TAG_REMOVEDTag was removed from subscribertagId, tagName, reason?

Workflow Events

Event TypeDescriptionData Fields
WORKFLOW_STARTEDSubscriber entered an automationworkflowId, workflowName
WORKFLOW_COMPLETEDSubscriber completed all workflow stepsworkflowId, workflowName
WORKFLOW_CANCELEDSubscriber was removed from workflowworkflowId, workflowName, reason?
WEBHOOK_EXECUTEDWebhook step was triggeredworkflowId, workflowName, stepId, webhookUrl, status, success, errorMessage?

Revenue Events

Event TypeDescriptionData Fields
SUBSCRIBER_PAYMENTSubscriber made a paymentamount, product
SUBSCRIBER_REFUNDSubscriber received refundamount, product

Other Events

Event TypeDescriptionData Fields
FIELD_UPDATEDCustom field value was updatedfieldId, fieldName, oldValue?, newValue

Usage Examples

Get recent activity

Retrieve the 20 most recent events for a subscriber:

curl "https://lumail.io/api/v1/subscribers/sub_123/events" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter by email engagement

Get only email open and click events:

curl 'https://lumail.io/api/v1/subscribers/sub_123/events?eventTypes=["EMAIL_OPENED","EMAIL_CLICKED"]' \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Date range filtering

Get events from the last 7 days:

curl "https://lumail.io/api/v1/subscribers/sub_123/events?startDate=2025-01-01T00:00:00Z&endDate=2025-01-07T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Search events

Search for events containing specific text:

curl "https://lumail.io/api/v1/subscribers/sub_123/events?search=newsletter" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Pagination

Fetch all events using cursor pagination:

async function getAllEvents(subscriberId) {
  const events = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({ take: "100" });
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(
      `https://lumail.io/api/v1/subscribers/${subscriberId}/events?${params}`,
      { headers: { Authorization: "Bearer YOUR_API_TOKEN" } },
    );
    const data = await response.json();

    events.push(...data.events);
    cursor = data.nextCursor;
  } while (cursor);

  return events;
}

Pagination with SDK

import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

async function getAllEvents(subscriberId: string) {
  const events = [];
  let cursor: string | null = null;

  do {
    const result = await lumail.subscribers.listEvents(subscriberId, {
      take: 100,
      cursor: cursor ?? undefined,
    });
    events.push(...result.events);
    cursor = result.nextCursor;
  } while (cursor);

  return events;
}
PreviousTrack EventNextGet All Tags