Messaging

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

Endpoints

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

List all messaging categories

Required API key scopes

hog_flow:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/messaging_categories
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_categories/

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",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}
]
}

Create messaging categories

Required API key scopes

hog_flow:write

Request parameters

  • key
    string
  • name
    string
  • description
    string
  • public_description
    string
  • category_type
  • deleted
    boolean

Response


Example request

POST /api/projects/:project_id/messaging_categories
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_categories/\
-d key="string",\
-d name="string"

Example response

Status 201
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Retrieve messaging categories

Required API key scopes

hog_flow:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/messaging_categories/: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_categories/:id/

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Update messaging categories

Required API key scopes

hog_flow:write

Path parameters

  • id
    string

Request parameters

  • key
    string
  • name
    string
  • description
    string
  • public_description
    string
  • category_type
  • deleted
    boolean

Response


Example request

PATCH /api/projects/:project_id/messaging_categories/: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_categories/:id/\
-d key="string"

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Delete messaging categories

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_categories/: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_categories/:id/

Example response

Status 405 No response body

Create messaging categories import from customerio

Import subscription topics and globally unsubscribed users from Customer.io API. Persists the App API key in Integration(kind="customerio-app"). If no app_api_key is provided, reuses the stored Integration key.

Request parameters

  • key
    string
  • name
    string
  • description
    string
  • public_description
    string
  • category_type
  • deleted
    boolean

Response


Example request

POST /api/projects/:project_id/messaging_categories/import_from_customerio
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_categories/import_from_customerio/\
-d key="string",\
-d name="string"

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Create messaging categories import preferences csv

Import customer preferences from CSV file Expected CSV columns: id, email, unsubscribed, cio_subscription_preferences


Response


Example request

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Retrieve messaging categories optout sync config

Get the Customer.io sync configuration state for this team. Used by the frontend to derive step completion.

Response


Example request

GET /api/projects/:project_id/messaging_categories/optout_sync_config
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_categories/optout_sync_config/

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Delete messaging categories remove customerio app config

Remove the Customer.io App API integration and reset import state.

Example request

DELETE /api/projects/:project_id/messaging_categories/remove_customerio_app_config
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_categories/remove_customerio_app_config/

Example response

Status 204 No response body

Delete messaging categories remove track config

Remove the Customer.io Track API integration and reset outbound sync state.

Example request

DELETE /api/projects/:project_id/messaging_categories/remove_track_config
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_categories/remove_track_config/

Example response

Status 204 No response body

Delete messaging categories remove webhook config

Remove the Customer.io webhook integration and reset inbound sync state.

Example request

DELETE /api/projects/:project_id/messaging_categories/remove_webhook_config
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_categories/remove_webhook_config/

Example response

Status 204 No response body

Create messaging categories save track config

Save Customer.io Track API credentials and/or toggle outbound sync.

Accepts:

  • site_id (optional): set on first creation only
  • api_key (optional): set on first creation only
  • region (optional): "us" or "eu", set on first creation only
  • track_enabled (required): enable or disable outbound sync

Request parameters

  • key
    string
  • name
    string
  • description
    string
  • public_description
    string
  • category_type
  • deleted
    boolean

Response


Example request

POST /api/projects/:project_id/messaging_categories/save_track_config
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_categories/save_track_config/\
-d key="string",\
-d name="string"

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}

Create messaging categories save webhook config

Save webhook signing secret and/or toggle the Customer.io webhook sync.

Accepts:

  • webhook_signing_secret (optional): set on first creation only
  • webhook_enabled (required): enable or disable the webhook

Request parameters

  • key
    string
  • name
    string
  • description
    string
  • public_description
    string
  • category_type
  • deleted
    boolean

Response


Example request

POST /api/projects/:project_id/messaging_categories/save_webhook_config
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_categories/save_webhook_config/\
-d key="string",\
-d name="string"

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"key": "string",
"name": "string",
"description": "string",
"public_description": "string",
"category_type": "marketing",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"created_by": 0,
"deleted": true
}