Messaging

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`PATCH`
`POST`
`POST`

List all messaging templates

Required API key scopes

hog_flow:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/messaging_templates
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "content": {
        "templating": "liquid",
        "email": {
          "subject": "string",
          "text": "string",
          "preheader": "string",
          "html": "string",
          "design": {
            "counters": {},
            "schemaVersion": 0,
            "body": {
              "id": "string",
              "rows": [
                {}
              ],
              "headers": [
                {}
              ],
              "footers": [
                {}
              ],
              "values": {}
            }
          },
          "from": {
            "email": "string",
            "name": "string",
            "integrationId": 0
          },
          "replyTo": "string"
        }
      },
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "type": "string",
      "message_category": "f74e6cc3-ac28-48ea-b195-3d593d7f03ec",
      "deleted": true,
      "sensitive": true,
      "transactional_hog_flow_id": "a8e25637-2aa3-4321-9b11-3c79bdd88594",
      "draft_content": {
        "templating": "liquid",
        "email": {
          "subject": "string",
          "text": "string",
          "preheader": "string",
          "html": "string",
          "design": {
            "counters": {},
            "schemaVersion": 0,
            "body": {
              "id": "string",
              "rows": [
                {}
              ],
              "headers": [
                {}
              ],
              "footers": [
                {}
              ],
              "values": {}
            }
          },
          "from": {
            "email": "string",
            "name": "string",
            "integrationId": 0
          },
          "replyTo": "string"
        }
      }
    }
  ]
}

Create messaging templates

Required API key scopes

hog_flow:write

Request parameters

name
string
description
string
tags
array
content
type
string
message_category
string | null
deleted
boolean
sensitive
boolean
draft_content

Response

Example request

POST /api/projects/:project_id/messaging_templates
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "type": "string",
  "message_category": "f74e6cc3-ac28-48ea-b195-3d593d7f03ec",
  "deleted": true,
  "sensitive": true,
  "transactional_hog_flow_id": "a8e25637-2aa3-4321-9b11-3c79bdd88594",
  "draft_content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  }
}

Retrieve messaging templates

Required API key scopes

hog_flow:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/messaging_templates/: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/messaging_templates/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/{messaging_template_id}/".format(
        project_id=project_id,
		messaging_template_id="<the messaging template id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "type": "string",
  "message_category": "f74e6cc3-ac28-48ea-b195-3d593d7f03ec",
  "deleted": true,
  "sensitive": true,
  "transactional_hog_flow_id": "a8e25637-2aa3-4321-9b11-3c79bdd88594",
  "draft_content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  }
}

Update messaging templates

Required API key scopes

hog_flow:write

Path parameters

id
string

Request parameters

name
string
description
string
tags
array
content
type
string
message_category
string | null
deleted
boolean
sensitive
boolean
draft_content

Response

Example request

PATCH /api/projects/:project_id/messaging_templates/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/{messaging_template_id}/".format(
        project_id=project_id,
		messaging_template_id="<the messaging template id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "type": "string",
  "message_category": "f74e6cc3-ac28-48ea-b195-3d593d7f03ec",
  "deleted": true,
  "sensitive": true,
  "transactional_hog_flow_id": "a8e25637-2aa3-4321-9b11-3c79bdd88594",
  "draft_content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  }
}

Delete messaging templates

Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true

Required API key scopes

hog_flow:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/messaging_templates/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/{messaging_template_id}/".format(
        project_id=project_id,
		messaging_template_id="<the messaging template id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 405 No response body

Update messaging templates design

Required API key scopes

hog_flow:write

Path parameters

id
string

Request parameters

operations
array

Response

Example request

PATCH /api/projects/:project_id/messaging_templates/:id/design
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/:id/design/\
	-d operations="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/{messaging_template_id}/design/".format(
        project_id=project_id,
		messaging_template_id="<the messaging template id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"operations": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "type": "string",
  "message_category": "f74e6cc3-ac28-48ea-b195-3d593d7f03ec",
  "deleted": true,
  "sensitive": true,
  "transactional_hog_flow_id": "a8e25637-2aa3-4321-9b11-3c79bdd88594",
  "draft_content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  }
}

Create messaging templates make transactional

Make this template sendable over the transactional email API. This creates the workflow that sends it, with its own metrics, run history and versions. This can't be undone: the template stays transactional. Transactional sends ignore marketing opt-outs. Calling it again on a transactional template changes nothing.

Required API key scopes

hog_flow:write

Path parameters

id
string

Request parameters

from_integration_id
integer | null

Response

Example request

POST /api/projects/:project_id/messaging_templates/:id/make_transactional
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/:id/make_transactional/\
	-d from_integration_id="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/{messaging_template_id}/make_transactional/".format(
        project_id=project_id,
		messaging_template_id="<the messaging template id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"from_integration_id": "integer"
	}
).json()

Example response

Status 200 The transactional template

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "tags": [
    "string"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "type": "string",
  "message_category": "f74e6cc3-ac28-48ea-b195-3d593d7f03ec",
  "deleted": true,
  "sensitive": true,
  "transactional_hog_flow_id": "a8e25637-2aa3-4321-9b11-3c79bdd88594",
  "draft_content": {
    "templating": "liquid",
    "email": {
      "subject": "string",
      "text": "string",
      "preheader": "string",
      "html": "string",
      "design": {
        "counters": {},
        "schemaVersion": 0,
        "body": {
          "id": "string",
          "rows": [
            {}
          ],
          "headers": [
            {}
          ],
          "footers": [
            {}
          ],
          "values": {}
        }
      },
      "from": {
        "email": "string",
        "name": "string",
        "integrationId": 0
      },
      "replyTo": "string"
    }
  }
}

Status 400 The template can't be sent, or there is no verified sender

Status 404 Template not found

Create messaging templates send

Send one transactional email from this template to one recipient. The template must be made transactional first. message_data fills the template's {{ variables.* }} placeholders. Transactional emails skip opt-outs and frequency caps. Send an Idempotency-Key header to retry safely without sending the email twice.

Required API key scopes

hog_flow:write

Path parameters

id
string

Request parameters

to
string
identifiers
message_data
object

Response

Example request

POST /api/projects/:project_id/messaging_templates/:id/send
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/messaging_templates/:id/send/\
	-d to="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/messaging_templates/{messaging_template_id}/send/".format(
        project_id=project_id,
		messaging_template_id="<the messaging template id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"to": "string"
	}
).json()

Example response

Status 202 Email queued

RESPONSE
{
  "message_id": "string",
  "replayed": true
}

Messaging

Endpoints

List all messaging templates

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create messaging templates

Required API key scopes

Request parameters

Response

Example request

Example response

Status 201

Retrieve messaging templates

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Update messaging templates

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete messaging templates

Required API key scopes

Path parameters

Example request

Example response

Status 405 No response body

Update messaging templates design

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Create messaging templates make transactional

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200 The transactional template

Status 400 The template can't be sent, or there is no verified sender

Status 404 Template not found

Create messaging templates send

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 202 Email queued

Status 400 The template isn't transactional or its email is paused, the recipient can't be used, or the Idempotency-Key is invalid

Status 404 Template not found

Status 409 A request with the same Idempotency-Key is still in progress

Status 422 The Idempotency-Key was already used for a different request

Status 429 Rate limited, or the project is over its email quota

Status 503 The email pipeline did not confirm the send