Transactional Email

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
GET
GET
GET
GET
GET
GET

List all transactional email log

List the project's transactional email sends, newest first. The log keeps sends for 30 days.

Required API key scopes

hog_flow:readperson:read

Query parameters

  • date_from
    string
  • date_to
    string
  • limit
    integer
    Default: 50
  • offset
    integer
    Default: 0
  • reason
    string
  • search
    string
  • status
    string
    One of: "queued""failed""sent""delivered""bounced""complained"
  • workflow_id
    string

Response


Example request

GET /api/projects/:project_id/transactional_email_log
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/

Example response

Status 200
RESPONSE
{
"results": [
{
"message_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"status": "queued",
"status_at": "2019-08-24T14:15:22Z",
"reason": "string",
"recipient": "string",
"workflow_id": "string",
"template_id": "string",
"template_name": "string",
"code_email_id": "string",
"sending_domain": "string",
"opened": true,
"clicked": true
}
],
"has_more": true
}

Retrieve transactional email log

Get one send with its timeline: when it was queued, sent, delivered, opened and clicked.

Required API key scopes

hog_flow:readperson:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/transactional_email_log/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/:id/

Example response

Status 200
RESPONSE
{
"message_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"status": "queued",
"status_at": "2019-08-24T14:15:22Z",
"reason": "string",
"recipient": "string",
"workflow_id": "string",
"template_id": "string",
"template_name": "string",
"code_email_id": "string",
"sending_domain": "string",
"opened": true,
"clicked": true,
"timeline": [
{
"kind": "queued",
"at": "2019-08-24T14:15:22Z",
"reason": "string"
}
],
"subject": "string",
"distinct_id": "string",
"action_id": "string",
"sensitive": true
}
Status 404 No send of this project has this ID, or it is older than the log keeps.

Retrieve transactional email log activity

The recipient's events in the 7 days before and after one send, with the sessions they belong to.

Required API key scopes

hog_flow:readperson:readquery:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/transactional_email_log/:id/activity
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/:id/activity/

Example response

Status 200
RESPONSE
{
"distinct_id": "string",
"sent_at": "2019-08-24T14:15:22Z",
"before": [
{
"uuid": "string",
"event": "string",
"timestamp": "2019-08-24T14:15:22Z",
"current_url": "string",
"pathname": "string",
"session_id": "string",
"event_type": "string",
"elements_chain": "string"
}
],
"after": [
{
"uuid": "string",
"event": "string",
"timestamp": "2019-08-24T14:15:22Z",
"current_url": "string",
"pathname": "string",
"session_id": "string",
"event_type": "string",
"elements_chain": "string"
}
],
"has_more_before": true,
"has_more_after": true,
"sessions": [
{
"session_id": "string",
"first_event_at": "2019-08-24T14:15:22Z",
"last_event_at": "2019-08-24T14:15:22Z",
"event_count": 0,
"started_after_send": true
}
]
}
Status 403 The user has no access to persons or to querying events.
Status 404 No send of this project has this ID, or it is older than the log keeps.

Retrieve transactional email log impact

Count one email's sends that were sent, delivered, opened and clicked. With an event, also count the clicked sends whose person did it within a week of the click, against delivered sends nobody clicked.

Required API key scopes

hog_flow:readquery:read

Query parameters

  • date_from
    string
  • date_to
    string
  • event
    string
  • workflow_id
    string

Response


Example request

GET /api/projects/:project_id/transactional_email_log/impact
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/impact/

Example response

Status 200
RESPONSE
{
"sent": 0,
"delivered": 0,
"opened": 0,
"clicked": 0,
"not_clicked": 0,
"untracked": 0,
"window_days": 0,
"after_click": {
"sends": 0,
"converted": 0
},
"without_click": {
"sends": 0,
"converted": 0
}
}
Status 403 The personal API key or OAuth token lacks the `hog_flow:read` or `query:read` scope, the user has no access to workflows in this project, or an event was named and the user has no access to querying events.
Status 404 The project has no such workflow, or the user may not view it.

Retrieve transactional email log results

Of the people a transactional email was sent to, count those who did an event within a window after their first send, and add up the revenue on those events.

Required API key scopes

hog_flow:readquery:read

Query parameters

  • date_from
    string
  • date_to
    string
  • event
    string
  • revenue_property
    string
  • window_days
    integer
    Default: 7
  • workflow_id
    string

Response


Example request

GET /api/projects/:project_id/transactional_email_log/results
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/results/

Example response

Status 200
RESPONSE
{
"recipients": 0,
"converted": 0,
"revenue": 0.1,
"median_hours_to_convert": 0
}
Status 403 The personal API key or OAuth token lacks the `hog_flow:read` or `query:read` scope, or the user has no access to workflows in this project or to querying events.
Status 404 The project has no such workflow, or the user may not view it.

Retrieve transactional email log stats

Count sends by delivery status, opens and clicks, per template or per sending domain.

Required API key scopes

hog_flow:read

Query parameters

  • date_from
    string
  • date_to
    string
  • group_by
    string
    Default: template
    One of: "template""sending_domain"

Response


Example request

GET /api/projects/:project_id/transactional_email_log/stats
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/stats/

Example response

Status 200
RESPONSE
{
"results": [
{
"key": "string",
"label": "string",
"template_id": "string",
"code_email_id": "string",
"sent": 0,
"delivered": 0,
"bounced": 0,
"complained": 0,
"opened": 0,
"clicked": 0,
"failed": 0
}
]
}

Retrieve transactional email log stats over time

Count sends by delivery status per time bucket, with totals for the period before.

Required API key scopes

hog_flow:read

Query parameters

  • date_from
    string
  • date_to
    string

Response


Example request

GET /api/projects/:project_id/transactional_email_log/stats_over_time
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/transactional_email_log/stats_over_time/

Example response

Status 200
RESPONSE
{
"interval": "minute",
"timezone": "string",
"buckets": [
{
"start": "2019-08-24T14:15:22Z",
"counts": {
"sent": 0,
"delivered": 0,
"bounced": 0,
"complained": 0,
"failed": 0
}
}
],
"previous": {
"sent": 0,
"delivered": 0,
"bounced": 0,
"complained": 0,
"failed": 0
}
}