--- title: "openemail events" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/events" area: "CLI" category: "Reference" --- # openemail events Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail events send` Record that something happened to a contact ```bash openemail events send --name [flags] openemail events send --data [flags] ``` Records an event against one contact, named by `email` or `--contact-id`: an order placed, a trial started, a plan changed. Every live automation whose trigger is this event name, and whose filters match `properties`, takes the contact in, and any wait step holding out for the name moves on. `enrolled` and `resumed` in the answer say what it set off. Events are kept for 90 days. Every call carries an `Idempotency-Key`. The SDK generates one per call and reuses it on that call's retries, so a retried network failure returns the stored event instead of recording a second one. Pass `--idempotency-key` to extend that across processes and restarts. A replay resolves with `replayed: true` and starts nothing again. The same key with a different event is a 422 `idempotency_key_reuse`. An event sent with a test key is stored with `mode` `test` and starts or resumes nothing. - Scopes: `contacts:write`. - Needs a sign-in. **Flags** - `--name `: What happened, such as `order.placed`: 1 to 100 letters, digits, dots, colons, dashes and underscores, starting with a letter or a digit. Names are matched exactly, case included. Required, here or in `--data`. - `--email `: The contact the event is about, by email address. Send this or `--contact-id`. - `--contact-id `: The contact the event is about, by id. Send this or `email`. - `--properties `: Anything worth keeping about the event, as an object of at most 50 keys and 4 KB of JSON. An event trigger can filter on these, and steps can put them in an email or a contact field. JSON shaped as `Record`, inline or from a file with @path. - `--occurred-at `: When it happened, as a `Date` or an ISO 8601 string. Left out, it is now. It cannot be in the future or more than 90 days ago. - `--create-contact`: Add the address to the contacts when nobody has it yet. It needs `email`. Left out or false, an unknown address is a 404 `contact_not_found`. - `--contact-name `: The name to give a contact that `--create-contact` adds, at most 200 characters. - `--idempotency-key `: Your own key, 1 to 255 characters of letters, digits, `_`, `.`, `:` or `-`. Anything else is a 400 `invalid_idempotency_key`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail events send --name order.placed ``` With optional flags ```bash openemail events send --name order.placed --email ada@example.com --create-contact --idempotency-key order:AC-4192:placed ``` Read the whole body from a JSON file ```bash openemail events send --data @event.json ``` Also available in: API [`POST /events`](https://openemail.uk/docs/api/reference/events#post-events); TypeScript [`events.send()`](https://openemail.uk/docs/sdk/reference/events#send); Python [`events.send()`](https://openemail.uk/docs/python/reference/events#send); Ruby [`events.send`](https://openemail.uk/docs/ruby/reference/events#send); PHP [`events->send`](https://openemail.uk/docs/php/reference/events#send); Go [`Events.Send`](https://openemail.uk/docs/go/reference/events#send); Java [`events().send`](https://openemail.uk/docs/java/reference/events#send); C# [`Events.SendAsync`](https://openemail.uk/docs/csharp/reference/events#send). ### `openemail events send-batch` Record up to 100 contact events in one call ```bash openemail events send-batch [flags] ``` Records each event in order, as if `events.send` had been called for it, and reports per event. It is never all or nothing: `accepted` holds the events that were stored and `failed` the ones that were not, each with the `index` it had in the array, so one unknown address does not stop the rest. The promise resolves whenever the batch was processed, so check `failed` instead of relying on a throw. The batch shares one `Idempotency-Key`, generated once per call or supplied as `--idempotency-key`, and the server remembers each event under the key and its position. Retrying the same array replays the events that were already stored and records only the ones that were not. Reordering the array between attempts makes an event that moved fail with `idempotency_key_reuse`. - Scopes: `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): The events, 1 to 100 of them, each in the shape `events.send` takes: `name`, `email` or `contactId`, and optionally `properties`, `occurredAt`, `createContact` and `contactName`. **Flags** - `--idempotency-key `: Your own key for the whole batch, 1 to 255 characters of letters, digits, `_`, `.`, `:` or `-`. **Examples** The required values only ```bash openemail events send-batch @events.json ``` With optional flags ```bash openemail events send-batch @events.json --idempotency-key trials:2026-10-11 ``` Also available in: API [`POST /events/batch`](https://openemail.uk/docs/api/reference/events#post-events-batch); TypeScript [`events.sendBatch()`](https://openemail.uk/docs/sdk/reference/events#sendBatch); Python [`events.send_batch()`](https://openemail.uk/docs/python/reference/events#sendBatch); Ruby [`events.send_batch`](https://openemail.uk/docs/ruby/reference/events#sendBatch); PHP [`events->sendBatch`](https://openemail.uk/docs/php/reference/events#sendBatch); Go [`Events.SendBatch`](https://openemail.uk/docs/go/reference/events#sendBatch); Java [`events().sendBatch`](https://openemail.uk/docs/java/reference/events#sendBatch); C# [`Events.SendBatchAsync`](https://openemail.uk/docs/csharp/reference/events#sendBatch). ### `openemail events list-names` List the event names the workspace has seen ```bash openemail events list-names [flags] ``` Returns the distinct names of the events the workspace holds, in byte order, at most 100. It is what the app suggests when somebody picks the event that starts an automation. Events are kept for 90 days, so a name nothing has sent in that time is gone. The list is not paginated. - Scopes: `automations:read`. - Needs a sign-in. **Examples** ```bash openemail events list-names ``` Print the raw JSON ```bash openemail events list-names --json ``` Also available in: API [`GET /events/names`](https://openemail.uk/docs/api/reference/events#get-events-names); TypeScript [`events.listNames()`](https://openemail.uk/docs/sdk/reference/events#listNames); Python [`events.list_names()`](https://openemail.uk/docs/python/reference/events#listNames); Ruby [`events.list_names`](https://openemail.uk/docs/ruby/reference/events#listNames); PHP [`events->listNames`](https://openemail.uk/docs/php/reference/events#listNames); Go [`Events.ListNames`](https://openemail.uk/docs/go/reference/events#listNames); Java [`events().listNames`](https://openemail.uk/docs/java/reference/events#listNames); C# [`Events.ListNamesAsync`](https://openemail.uk/docs/csharp/reference/events#listNames).