# Events & automations

> Send custom events from your app to start API-event automations in Mailmanny.

Source: https://www.mailmanny.com/docs/events
All docs for AI agents: https://www.mailmanny.com/llms.txt

Tell Mailmanny when something happens in your app, like a signup, an order or a trial ending, and let an automation send the right emails at the right time.

## Track an event

`POST /api/v1/events` (permission: `events:write`)

**Node.js SDK**

```ts
await mm.events.track({
  audienceId,
  email: "sam@example.com",
  name: "order.completed",
  properties: { total: 42.5, items: 3 },
});
```

**curl**

```bash
curl -X POST https://www.mailmanny.com/api/v1/events \
  -H "Authorization: Bearer $MAILMANNY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-completed" \
  -d '{
    "audience_id": "0199e9c1-2f3a-7b4c-8d5e-6f7a8b9c0d1e",
    "email": "sam@example.com",
    "name": "order.completed",
    "properties": { "total": 42.5, "items": 3 }
  }'
```

**202 Accepted**

```json
{
  "object": "event",
  "id": "01JABCDE4XKQ2V7M9N3P5R8S0T",
  "name": "order.completed",
  "contact_id": "0199f0b2-6c1e-7a3d-9f2b-3c4d5e6f7a8b",
  "accepted": true
}
```

- `audience_id` (string, required): The audience the contact belongs to.
- `email` (string, required): The contact. They must already be in the audience.
- `name` (string, required): Up to 100 characters: letters, numbers, dots, colons, dashes and underscores, e.g. order.completed.
- `properties` (object): Any JSON details about the event, up to 16 KB.

The response is 202 because automations run in the background. A contact that isn't in the audience gets 404 `not_found`: add them first with [POST /contacts](https://www.mailmanny.com/docs/contacts.md).

> **Note:** On Standard and Pro
> Events start automations, and API event triggers are on Standard and Pro (from $14 a month). On Free and Essentials, `POST /events` answers 402 `plan_required`. See [pricing](https://www.mailmanny.com/pricing).

## Start an automation

1. In [Automations](https://www.mailmanny.com/automations), create an automation on the same audience and pick the **API event** trigger.
2. Enter the event name exactly as you send it, for example `order.completed`.
3. Build the steps (wait, send email, add tag, split) and turn it on.

Every matching event then starts a run for that contact. The automation's own settings decide whether someone can enter more than once, and its filters decide who may enter at all. Unsubscribed contacts never receive its emails.

> **Good to know:** Retries never double-send
> Pass an `Idempotency-Key`. Events with the same key within 24 hours start an automation only once, so you can retry a timed-out request without sending two welcome emails. See [Idempotency](https://www.mailmanny.com/docs/idempotency.md).

## Example: post-purchase series

**checkout.ts**

```ts
// After a successful checkout
await mm.contacts.create({ audienceId, email: order.email, firstName: order.firstName, tags: ["customer"] });
await mm.events.track(
  { audienceId, email: order.email, name: "order.completed", properties: { total: order.total } },
  { idempotencyKey: `order-${order.id}-completed` },
);
```

An automation on `order.completed` can wait three days, send a "How was it?" email, and tag people who click the review link. Events are a better fit than tags for things that repeat, like orders.