---
title: "Report a workflow event"
method: POST
path: "/events"
tags: ["workflows"]
---

# Report a workflow event

`POST /events`

## Request

- Base URL: `https://api.mailly.site` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mailly.site/events`
- Auth: HTTP bearer

Stores the event idempotently, then triggers or exits workflows; a duplicate event returns 200 and a new event returns 201.

## Request body

- object: Workflow event input
  - `event_id` string, required: Stable event ID (idempotency key); retries must reuse it
  - `event_name` string, required: Event name (matched against trigger and exit conditions)
  - `occurred_at` string, required: Event time, ISO-8601
  - `contact` object, required: Contact
    - `external_contact_id` string, required: Stable business-side contact ID
    - `email` string, required: Contact email
    - `attributes` object: Contact attributes, JSON up to 32KB
  - `properties` object: Event properties, JSON up to 64KB

## Response `200`

Duplicate event (idempotent)

- object
  - `success` boolean, required
  - `duplicate` boolean, required
  - `event` object, required

## Other responses

- `201`: Accepted
- `400`: Invalid parameters
- `401`: Missing or invalid API key
- `409`: Event conflict
- `500`: Processing failed

---

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