Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DataTalksClub/datamailer/llms.txt

Use this file to discover all available pages before exploring further.

GET /api/contacts.csv returns a CSV file containing every contact that has a subscription record for the specified audience and client. The export includes subscription status, verification timestamps, tag assignments, email validation results, suppression flags, unsubscribe details, and the contact’s last updated_at timestamp — enough to recreate the full contact state in an external system or re-import it later. A companion JSON endpoint (GET /api/contacts) returns the same contact set as a paginated JSON array.

​
Authentication

All requests must include a Bearer token issued for the target client. 
Authorization: Bearer <client-api-key>

​
Endpoints

MethodPathResponse
GET/api/contacts.csvCSV file download
GET/api/contactsPaginated JSON array

​
Query Parameters

​
audience
string
required
Slug of the audience to export. Only contacts with a subscription for this audience and the authenticated client are included.
​
client
string
required
Slug of the authenticated client. Must match the token’s client slug.
​
tags
string
Comma-separated tag slugs to filter by. Only contacts that have all listed tags are returned.
​
subscription_status
string
Filter to contacts with this subscription status. One of pending, subscribed, or unsubscribed.
​
verified
string
Filter to verified (true) or unverified (false) contacts. Accepts the same boolean strings as the CSV import (true, 1, yes, false, 0, no).
​
email_validation_status
string
Filter by email validation status. One of unknown, valid, invalid_syntax, no_mx, disposable, risky, manually_invalid, or externally_validated.
​
suppression
string
Filter by suppression state. One of none (no suppression flags set), any (at least one flag set), global_unsubscribed, hard_bounced, or complained.
​
updated_since
string
ISO 8601 datetime. Only contacts with updated_at at or after this timestamp are returned. Useful for incremental sync.
​
limit
integer
CSV export: Maximum rows to include. Defaults to 10000, maximum 10000.JSON export: Page size. Defaults to 50, maximum 500.
​
cursor
integer
JSON export only. Contact ID used as a cursor for pagination. Pass the next_cursor value from the previous response to fetch the next page.

​
CSV Response

Content-Type: text/csv; charset=utf-8 Content-Disposition: attachment; filename="contacts.csv" The CSV file includes the following columns in this order:
ColumnDescription
emailNormalized (lowercased) email address.
audienceAudience slug for this export scope.
clientClient slug for this export scope.
tagsSemicolon-separated tag slugs assigned within this audience.
subscription_statuspending, subscribed, or unsubscribed.
verifiedTrue or False.
verified_atISO 8601 timestamp, or empty.
email_validation_statusValidation status string.
email_validation_reasonHuman-readable validation reason.
email_validated_atISO 8601 timestamp of last validation, or empty.
global_unsubscribedTrue or False.
hard_bouncedTrue or False.
complainedTrue or False.
unsubscribedTrue when subscription_status is unsubscribed.
unsubscribed_atISO 8601 timestamp, or empty.
unsubscribe_reasonStored unsubscribe reason string.
updated_atISO 8601 timestamp of the contact’s last modification.

​
JSON Response

The JSON endpoint (GET /api/contacts) returns a paginated object:
​
audience
string
Audience slug.
​
client
string
Client slug.
​
count
integer
Number of contacts in this page.
​
next_cursor
string | null
Pass this value as the cursor query parameter to fetch the next page. null when there are no more results.
​
contacts
object[]
Array of contact objects, each containing the same fields as the upsert response plus subscription_status, unsubscribed, unsubscribed_at, unsubscribe_reason, created_at, and updated_at.

​
Examples

​
Export all subscribed contacts as CSV

curl -G "https://datamailer.example.com/api/contacts.csv" \
  -H "Authorization: Bearer dm_dtcnews_demo_newsletter_import_export_key" \
  --data-urlencode "audience=dtc-courses" \
  --data-urlencode "client=dtc-courses" \
  --data-urlencode "subscription_status=subscribed" \
  -o contacts.csv

​
Export contacts updated in the last 24 hours as JSON

curl -G "https://datamailer.example.com/api/contacts" \
  -H "Authorization: Bearer dm_dtcnews_demo_newsletter_import_export_key" \
  --data-urlencode "audience=dtc-courses" \
  --data-urlencode "client=dtc-courses" \
  --data-urlencode "updated_since=2024-09-01T00:00:00Z"

​
Sample CSV output

email,audience,client,tags,subscription_status,verified,verified_at,email_validation_status,email_validation_reason,email_validated_at,global_unsubscribed,hard_bounced,complained,unsubscribed,unsubscribed_at,unsubscribe_reason,updated_at
learner@example.com,dtc-courses,dtc-courses,course-ml-zoomcamp;course-de-zoomcamp,subscribed,True,2024-09-01T10:00:00Z,unknown,,False,False,False,False,,,2024-09-01T10:00:00Z
student@example.com,dtc-courses,dtc-courses,course-de-zoomcamp,subscribed,False,,valid,smtp-check,2024-09-02T08:30:00Z,False,False,False,False,,,2024-09-02T08:30:00Z
The export is scoped to the authenticated client. Only contacts that have a matching subscription record for both the specified audience and the authenticated client are returned. Contacts that exist in Datamailer but have never been subscribed through this client will not appear in the output.

Build docs developers (and LLMs) love

Get started for freeTalk to us