CSV Exports

Two paths for exporting log data: (1) synchronous email-log CSV stream via signed token; (2) async API-request-log CSV emailed as an attachment because the table is too large to stream live.

Posthawk has two export pipelines depending on data size:

Email logs (synchronous stream)

For email_logs (sent + received emails), the export is a streamed CSV download. You first request a signed token, then redirect the browser to the worker's CSV endpoint with that token. The browser receives the CSV as a file download.

This is what the dashboard's "Export CSV" button on the Logs page does.

Token TTL is 5 minutes and consumed on first use. Date range is capped at 31 days.

API request logs (async, emailed)

The request_logs table records every authenticated HTTP request to the worker. It can hold tens of millions of rows for a busy workspace, so synchronous streaming would time out. Instead, the export is queued as a BullMQ job — the worker compiles the CSV and emails it to you as an attachment when ready (typically within a minute).

This is what the dashboard's "Export CSV" button on the Logs API tab does.

POST/export/token

Request a signed token for an email-log CSV export. Token is valid for 5 minutes and consumed on first use.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your JWT.

Body

typestringrequired

"sent" | "received" | "both"

dateFromstringrequired

ISO 8601 datetime (max 31 days back)

dateTostringrequired

ISO 8601 datetime

statusesstring[]optional

Filter by email_logs.status: queued, processing, sent, delivered, bounced, complained, failed

apiKeyIdstringoptional

Filter sent emails to a specific API key (sent type only)

domainIdstringoptional

Filter received emails to a specific domain (received type only)

POST /export/token

curl -X POST https://api.posthawk.dev/export/token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "type": "sent",
    "dateFrom": "2026-04-01T00:00:00Z",
    "dateTo": "2026-04-30T23:59:59Z",
    "statuses": [
      "delivered",
      "bounced"
    ],
    "apiKeyId": "api-key-uuid",
    "domainId": "domain-uuid"
  }'

Response

{ "token": "signed.jwt.string", "expiresIn": 300 }

GET/export/csv?token=...

Download the CSV. Browser-redirected from the dashboard with the token from the previous step. Streams the CSV with Content-Disposition: attachment.

Authorizations

No authentication required — this is a public endpoint.

Query Parameters

tokenstringrequired

Signed token from POST /export/token (5min TTL, consumed on first use)

GET /export/csv?token=...

curl "https://api.posthawk.dev/export/csv?token=..."

POST/export/request-logs

Queue an async request-logs export. The worker compiles the CSV and emails it to you as an attachment when ready. Date range capped at 31 days.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your JWT.

Body

dateFromstringrequired

ISO 8601 datetime

dateTostringrequired

ISO 8601 datetime (max 31 days from dateFrom)

methodstringoptional

HTTP method filter (GET, POST, PATCH, PUT, DELETE)

statusRangestringoptional

"2xx" | "4xx" | "5xx"

POST /export/request-logs

curl -X POST https://api.posthawk.dev/export/request-logs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "dateFrom": "2026-04-01T00:00:00Z",
    "dateTo": "2026-04-30T23:59:59Z",
    "method": "POST",
    "statusRange": "2xx"
  }'

Response

{
  "success": true,
  "message": "Export queued. You will receive an email with the CSV attached when ready."
}

Audit Log Schema

Self-Hosting