API reference

Events

Things your users do, like signed_up or project_created. Events start and stop sequences and can target broadcasts. Record them from your app's code.

Mailpark records one event itself: mail_opened, the first time a person opens an email (real opens and clicks, not automatic pre-loads).

Event types describe the kinds you record. They appear on their own the first time a new name is recorded; define one up front to document its data.

The Event object

type Event = {
  id: string;                  // evt_…
  contact_id: string;
  name: string;
  data: Record<string, unknown>;
  occurred_at: string;
};

Record an event

POST/v1/events

Records something a user did. Identify the contact by email, contact id or your external id. Returns the sequences the event enrolled the contact in or took them out of.

scope events:write

Body

namestringrequired
Event name, e.g. signed_up.
emailstring
The contact's email. A new address creates the contact.
contact_idstring
Or the contact id.
external_idstring
Or your own user id.
dataobject
Anything about the event.
occurred_atstring
ISO-8601. Defaults to now.

curl -X POST https://api.mailpark.io/v1/events \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "signed_up",
    "email": "jane@example.com",
    "data": {
      "plan": "trial"
    }
  }'

Response · 200

{
  "id": "evt_8Kd2",
  "contact_id": "con_7Yt1",
  "enrolled_in": [
    "seq_onboard"
  ],
  "exited_from": [],
  "next_steps": [
    "Jane entered Onboarding. Watch it with GET /v1/sequences/seq_onboard/enrollments."
  ]
}

▶ Try it in the playground

List events

GET/v1/events

Recent events for one contact, or for the whole account without a query.

scope logs:read

Query parameters

contactstring
A contact id or email.
limitinteger
How many to return, 1–100. Default 50.
cursorstring
The next_cursor from the previous page.

curl 'https://api.mailpark.io/v1/events?contact=jane%40example.com' \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "data": [
    {
      "id": "evt_8Kd2",
      "contact_id": "con_7Yt1",
      "name": "signed_up",
      "data": {
        "plan": "trial"
      },
      "occurred_at": "2026-10-22T10:02:11Z"
    }
  ],
  "next_cursor": null
}

▶ Try it in the playground

List event types

GET/v1/event-types

Every kind of event, most recorded first, with counts and the sequences that use it.

curl https://api.mailpark.io/v1/event-types \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "data": [
    {
      "name": "project_created",
      "description": "The user created their first project.",
      "properties": [
        {
          "key": "project_id",
          "type": "string",
          "description": "The new project's id."
        }
      ],
      "defined": true,
      "defined_at": "2026-10-01T12:00:00Z",
      "first_seen": "2026-10-02T09:12:00Z",
      "last_seen": "2026-10-22T10:02:11Z",
      "count": 318,
      "sequences": [
        {
          "id": "seq_onboard",
          "name": "Onboarding",
          "status": "on",
          "role": "exit"
        }
      ]
    }
  ]
}

▶ Try it in the playground

Define an event type

POST/v1/event-types

Documents an event before you record it: what it means and which data properties it carries. Events aren't rejected when their data doesn't match.

scope events:write

Body

namestringrequired
Event name.
descriptionstring
What it means.
propertiesobject[]
The data you send with it.
- keystringrequired
  Property name.
- typestringrequired
  string, number, boolean, object or array.
- descriptionstring
  What it holds.

curl -X POST https://api.mailpark.io/v1/event-types \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project_created",
    "description": "The user created their first project.",
    "properties": [
      {
        "key": "project_id",
        "type": "string",
        "description": "The new project'\''s id."
      }
    ]
  }'

Response · 200

{
  "name": "project_created",
  "description": "The user created their first project.",
  "properties": [
    {
      "key": "project_id",
      "type": "string",
      "description": "The new project's id."
    }
  ],
  "defined": true,
  "defined_at": "2026-10-01T12:00:00Z",
  "first_seen": "2026-10-02T09:12:00Z",
  "last_seen": "2026-10-22T10:02:11Z",
  "count": 318,
  "sequences": [
    {
      "id": "seq_onboard",
      "name": "Onboarding",
      "status": "on",
      "role": "exit"
    }
  ],
  "next_steps": [
    "Record it from your app with POST /v1/events { name: \"project_created\" }."
  ]
}

▶ Try it in the playground

Get an event type

GET/v1/event-types/{name}

One event type with its properties, counts and sequences.

Path parameters

namestringrequired
Event name.

curl https://api.mailpark.io/v1/event-types/project_created \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "name": "project_created",
  "description": "The user created their first project.",
  "properties": [
    {
      "key": "project_id",
      "type": "string",
      "description": "The new project's id."
    }
  ],
  "defined": true,
  "defined_at": "2026-10-01T12:00:00Z",
  "first_seen": "2026-10-02T09:12:00Z",
  "last_seen": "2026-10-22T10:02:11Z",
  "count": 318,
  "sequences": [
    {
      "id": "seq_onboard",
      "name": "Onboarding",
      "status": "on",
      "role": "exit"
    }
  ]
}

▶ Try it in the playground

Update an event type

PATCH/v1/event-types/{name}

Changes the description or properties. properties replaces the whole list.

scope events:write

Path parameters

namestringrequired
Event name.

Body

descriptionstring
What it means.
propertiesobject[]
The full list of properties.

curl -X PATCH https://api.mailpark.io/v1/event-types/project_created \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "The user created a project."
  }'

Response · 200

{
  "name": "project_created",
  "description": "The user created a project.",
  "properties": [
    {
      "key": "project_id",
      "type": "string",
      "description": "The new project's id."
    }
  ],
  "defined": true,
  "defined_at": "2026-10-01T12:00:00Z",
  "first_seen": "2026-10-02T09:12:00Z",
  "last_seen": "2026-10-22T10:02:11Z",
  "count": 318,
  "sequences": [
    {
      "id": "seq_onboard",
      "name": "Onboarding",
      "status": "on",
      "role": "exit"
    }
  ]
}

▶ Try it in the playground

Delete an event type

DELETE/v1/event-types/{name}

Removes the definition. If events of this kind were recorded, their history stays and only the description and properties go.

scope events:write

Path parameters

namestringrequired
Event name.

curl -X DELETE https://api.mailpark.io/v1/event-types/project_created \
  -H "Authorization: Bearer $MAILPARK_API_KEY"

Response · 200

{
  "deleted": true,
  "name": "project_created",
  "kept_history": true,
  "next_steps": []
}

▶ Try it in the playground