> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailerpath.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Send Events

> Step-by-step event submission flow with processing expectations.

Use this guide to integrate event submission safely and predictably.

For the canonical event types, action values, status values, and tag mappings, see [Event vocabulary](/documentation/events/event-vocabulary).

## 1) Build A Valid Event Payload

Required:

* type
* at least one contact identifier: email or uid

Common optional fields:

* source
* action
* feature
* plan
* amount
* status
* upgrade
* idempotency\_key
* external\_id
* ts
* metadata

Example payload:

```json theme={null}
{
	"email": "buyer@example.com",
	"type": "purchase",
	"source": "api",
	"action": "renewed",
	"feature": "billing",
	"plan": "pro",
	"amount": 49.9,
	"status": "success",
	"upgrade": false,
	"idempotency_key": "purchase-buyer-example-com-20260622",
	"ts": "2026-06-22T10:30:00Z"
}
```

## 2) Send The Event

Single event endpoint:

* POST /api/v1/client/events

Bulk endpoint:

* POST /api/v1/client/events/bulk

Request example:

```bash theme={null}
curl -X POST "https://your-api-domain/api/v1/client/events" \
	-H "Authorization: Bearer <token>" \
	-H "Content-Type: application/json" \
	-d '{
		"email": "buyer@example.com",
		"type": "purchase",
		"status": "success",
		"idempotency_key": "purchase-buyer-example-com-20260622"
	}'
```

## 3) Expect Async Processing

1. Client sends event payload.
2. API accepts request.
3. Event enters incoming inbox processing.
4. On success, canonical event is created.
5. On failure, inbox shows error and retry state.

Typical behavior:

* create may return accepted or success depending on sync mode and environment behavior
* canonical event may appear shortly after inbox entry

## 4) Verify In Incoming Events

Use:

* GET /api/v1/public/authenticated/events/incoming

Check fields:

* status
* process\_error
* retryable
* retry\_count
* event\_id

When event\_id is present, the canonical event is linked.

## 5) Verify In Canonical Events

Use:

* GET /api/v1/public/authenticated/events

Use filters such as:

* event\_type
* source
* status
* from
* to
* q

## 6) Idempotency Strategy

Use a deterministic key for retriable client operations.

Recommended key pattern:

* `<event_type>-<contact_identifier>-<logical_event_time_or_sequence>`

Example:

* purchase-user\_123-20260622T103000Z

## 7) Polling Strategy

Recommended UI pattern:

1. Load Events and Incoming Events in parallel.
2. Poll Incoming Events every 5 to 15 seconds while page is visible.
3. Stop polling when no rows are received or processing.

## Common Integration Mistakes

* missing contact identity fields
* inconsistent event type naming across clients
* non-deterministic idempotency keys
* assuming canonical list updates instantly
* ignoring terminal failures in incoming events