---
title: "Ingest a custom event for automations"
method: POST
path: "/events"
tags: ["Events"]
---

# Ingest a custom event for automations

`POST /events`

## Request

- Base URL: `https://api.groundmail.dev`
- URL: `https://api.groundmail.dev/events`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `name` string, required: Canonical event name (alias: `type`)
    - `type` string: Alias for name
    - `user_id` string
    - `userId` string: Alias for user_id
    - `email` string, email
    - `data` object
  - object
    - `name` string: Canonical event name (alias: `type`)
    - `type` string, required: Alias for name
    - `user_id` string
    - `userId` string: Alias for user_id
    - `email` string, email
    - `data` object

## Response `202`

Event accepted for automation processing

- TriggerEventResponse
  - `event` EventRecord, required
    - `id` string, required
    - `name` string, required
    - `user_id` string, nullable, required
    - `email` string, email, nullable, required
    - `data` object, required
    - `source` 'api' | 'dashboard', required
    - `created_at` string, date-time, required
  - `matched_automations` integer, required
  - `resumed_runs` integer, required
  - `cancelled_runs` integer, required: Active runs cancelled because this event matched `trigger.cancel_on_events`
  - `skipped_enrollments` integer: Automations whose trigger matched but did not start a run, because of `trigger.once_per_contact` or `trigger.cooldown_days`
  - `enrollment_skips` object[]: Present when `skipped_enrollments` is above zero. One entry per automation that declined to enrol this recipient again.
    - `automation_id` string, required
    - `reason` 'once_per_contact' | 'cooldown', required
    - `prior_run_id` string, required
    - `prior_run_at` string, date-time, required

## Other responses

- `400`: Invalid event payload
- `401`: Missing or invalid API key / session
- `409`: Idempotency conflict

---

[API](https://skmtc.dev/groundmail/apis/groundmail-api.md) · [All operations](https://skmtc.dev/groundmail/apis/groundmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/groundmail/apis/groundmail-api/revisions/479821c9fecf?raw)