`https://lumail.io/api/v1/events`

Records a new event for a subscriber. Events appear in the subscriber timeline and can be used for segmentation and automation triggers.

## Response

- **Success (200 OK)** - Returns the created event object.
- **Error (400 Bad Request)** - Returned if the subscriber is not found or the event data is invalid.
- **Error (500 Internal Server Error)** - Returned if the event could not be created.

## Response Fields

| Field                  | Type    | Description                                    |
| ---------------------- | ------- | ---------------------------------------------- |
| `success`              | boolean | Indicates if the operation was successful      |
| `event`                | object  | The created event object                       |
| `event.id`             | string  | Unique identifier for the event                |
| `event.eventType`      | string  | Type of the event                              |
| `event.subscriberId`   | string  | ID of the subscriber associated with the event |
| `event.organizationId` | string  | ID of the organization                         |
| `event.data`           | object  | Additional data specific to the event type     |
| `event.createdAt`      | string  | ISO timestamp when the event was created       |

## Request Schema

```json
{
  "eventType": "string", // Required: Type of event from predefined list
  "subscriber": "string", // Required: Email or ID of the subscriber
  "data": {
    // Required: Additional event data
    "property1": "value1",
    "property2": "value2"
  }
}
```

Supported event types:

- `SUBSCRIBED` - Subscriber joined a list
- `UNSUBSCRIBED` - Subscriber opted out
- `TAG_ADDED` - Tag was applied to subscriber
- `TAG_REMOVED` - Tag was removed from subscriber
- `EMAIL_OPENED` - Subscriber opened an email
- `EMAIL_CLICKED` - Subscriber clicked a link in an email
- `EMAIL_SENT` - Email was sent to subscriber
- `EMAIL_RECEIVED` - Email was successfully delivered
- `WORKFLOW_STARTED` - Subscriber entered a workflow
- `WORKFLOW_COMPLETED` - Subscriber completed a workflow
- `WORKFLOW_CANCELED` - Subscriber was removed from a workflow
- `FIELD_UPDATED` - Custom field was updated for subscriber
- `EMAIL_BOUNCED` - Email to subscriber bounced
- `EMAIL_COMPLAINED` - Subscriber marked email as spam
- `WEBHOOK_EXECUTED` - Webhook was triggered for subscriber
- `SUBSCRIBER_PAYMENT` - Subscriber made a payment
- `SUBSCRIBER_REFUND` - Subscriber received a refund

## Usage Example

Use this API endpoint to track important subscriber activities and interactions:

- Record purchase events with amount and product data
- Track website engagement like page visits or feature usage
- Log subscriber lifecycle events (registration, upgrade, cancellation)
- Store third-party system interactions
- Trigger automation workflows based on specific events
- Build a comprehensive timeline of subscriber activity

## Related Documentation

- [Subscriber Events Reference](/docs/features/subscriber-events) - Complete guide to all event types and their data fields
- [Get Subscriber Events API](/docs/api-reference/api-subscriber-events-get) - Retrieve event history for a subscriber


## API Reference
**Method:** POST
**Endpoint:** /api/v1/events

### SDK
```ts
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

const { event } = await lumail.events.create({
  eventType: "SUBSCRIBER_PAYMENT",
  subscriber: "subscriber@example.com",
  data: {
    amount: 49.99,
    currency: "USD",
    productName: "Premium Subscription",
  },
});
console.log(event);
```

### cURL
```bash
curl -X POST https://lumail.io/api/v1/events \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "SUBSCRIBER_PAYMENT",
    "subscriber": "subscriber@example.com",
    "data": {
      "amount": 49.99,
      "currency": "USD",
      "productName": "Premium Subscription"
    }
  }'
```

### JavaScript
```javascript
const response = await fetch('https://lumail.io/api/v1/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    eventType: 'SUBSCRIBER_PAYMENT',
    subscriber: 'subscriber@example.com',
    data: {
      amount: 49.99,
      currency: 'USD',
      productName: 'Premium Subscription'
    }
  }),
});

const data = await response.json();
console.log(data);
```

### Python
```python
import requests

url = "https://lumail.io/api/v1/events"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "eventType": "SUBSCRIBER_PAYMENT",
    "subscriber": "subscriber@example.com",
    "data": {
        "amount": 49.99,
        "currency": "USD",
        "productName": "Premium Subscription"
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)
```

### Success Response
```json
{
  "success": true,
  "event": {
    "id": "evt_6fGhIjKl78",
    "eventType": "SUBSCRIBER_PAYMENT",
    "subscriberId": "sub_TTYPR5tWDh",
    "organizationId": "HEnp-DaJnmI",
    "data": {
      "amount": 49.99,
      "currency": "USD",
      "productName": "Premium Subscription"
    },
    "createdAt": "2025-04-27T06:12:34.567Z"
  }
}
```

### Error Response
```json
{
  "message": "Subscriber not found"
}
```