Contacts API

Retrieve aggregated engagement data per recipient across all campaigns.

List Contacts

Get a list of all contacts with their engagement metrics.

Endpoint


GET /api/contacts

Query Parameters

Parameter	Type	Required	Description
`search`	`string`	No	Filter contacts by email address

Example Request


curl -X GET "NEXT_PUBLIC_BASE_URL/api/contacts?search=john" \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`email`	`string`	Recipient email address
`totalEmails`	`number`	Total emails sent to this contact
`totalOpens`	`number`	Total open events
`totalClicks`	`number`	Total click events
`campaigns`	`string[]`	Campaign names the contact received
`engagementScore`	`number`	Score from 0 to 100
`lastActivity`	`string`	ISO 8601 timestamp of most recent activity

Engagement Score Formula


openRate = totalOpens / totalEmails
clickRate = totalClicks / totalEmails
engagementScore = min(100, round((openRate * 60 + clickRate * 40) * 100))

Example Response


[
  {
    "email": "john@example.com",
    "totalEmails": 24,
    "totalOpens": 18,
    "totalClicks": 7,
    "campaigns": ["Welcome Series", "Newsletter January"],
    "engagementScore": 57,
    "lastActivity": "2024-03-14T16:45:00.000Z"
  },
  {
    "email": "jane@example.com",
    "totalEmails": 12,
    "totalOpens": 12,
    "totalClicks": 5,
    "campaigns": ["Newsletter January"],
    "engagementScore": 77,
    "lastActivity": "2024-03-13T09:30:00.000Z"
  }
]

Get Contact Detail

Get detailed engagement information for a specific contact, including a full activity timeline.

Endpoint


GET /api/contacts/:email

Path Parameters

Parameter	Type	Description
`email`	`string`	URL-encoded email address

Example Request


curl -X GET NEXT_PUBLIC_BASE_URL/api/contacts/john%40example.com \
  -H "x-api-key: your-api-key"

Response Schema

Field	Type	Description
`email`	`string`	Recipient email address
`totalEmails`	`number`	Total emails sent
`totalOpens`	`number`	Total open events
`totalClicks`	`number`	Total click events
`campaigns`	`string[]`	Campaign names
`engagementScore`	`number`	Score from 0 to 100
`lastActivity`	`string`	ISO 8601 most recent activity
`firstSeen`	`string`	ISO 8601 first email sent
`openRate`	`number`	Opens per email ratio
`clickRate`	`number`	Clicks per email ratio
`timeline`	`TimelineEvent[]`	Chronological list of events

TimelineEvent Schema

Field	Type	Description
`type`	`string`	`"sent"`, `"opened"`, or `"clicked"`
`timestamp`	`string`	ISO 8601 event timestamp
`subject`	`string`	Email subject line
`campaign`	`string`	Campaign name (optional)
`link`	`string`	Clicked URL (only for `"clicked"` events)

Example Response


{
  "email": "john@example.com",
  "totalEmails": 24,
  "totalOpens": 18,
  "totalClicks": 7,
  "campaigns": ["Welcome Series", "Newsletter January"],
  "engagementScore": 57,
  "lastActivity": "2024-03-14T16:45:00.000Z",
  "firstSeen": "2024-01-05T08:00:00.000Z",
  "openRate": 0.75,
  "clickRate": 0.29,
  "timeline": [
    {
      "type": "clicked",
      "timestamp": "2024-03-14T16:45:00.000Z",
      "subject": "March Newsletter",
      "campaign": "Newsletter January",
      "link": "https://example.com/promo"
    },
    {
      "type": "opened",
      "timestamp": "2024-03-14T16:40:00.000Z",
      "subject": "March Newsletter",
      "campaign": "Newsletter January"
    },
    {
      "type": "sent",
      "timestamp": "2024-03-14T10:00:00.000Z",
      "subject": "March Newsletter",
      "campaign": "Newsletter January"
    }
  ]
}

Error Responses

Status	Description
`401 Unauthorized`	Invalid or missing API key
`404 Not Found`	Contact not found in your organization

Example Error


{
  "error": "Contact not found"
}