# Track Event

`POST https://api.inboxjot.com/v1/events`

Records an event for a contact, such as a signup or a purchase. Inboxjot creates the contact when the address is new, then starts the automations that wait for this event. Needs a Full key. A key limited to one domain answers 403. Send an optional `Idempotency-Key` header to retry safely. See Idempotency.

## Body Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Event name, 1 to 100 characters. Start with a letter or number, then use letters, numbers, `.`, `_`, `:` or `-`. |
| `email` | string | Yes | The contact address. A new address creates a subscribed contact. Disposable addresses are refused. |
| `data` | object | No | Event data, such as `{ "plan": "pro" }`, up to 16 KB as JSON. Automations started by the event can use it in their emails. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `contact_id` | string | No | The contact the event belongs to. |

## Request

cURL:

```bash
curl -X POST https://api.inboxjot.com/v1/events \
  -H "Authorization: Bearer $INBOXJOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order.completed",
    "email": "riti@example.com",
    "data": {
      "order_id": "4821",
      "total": 49
    }
  }'
```

Node.js:

```javascript
import { Inboxjot } from 'inboxjot';

const inboxjot = new Inboxjot();

await inboxjot.events.send({
  name: 'order.completed',
  email: 'riti@example.com',
  data: { order_id: '4821', total: 49 },
});
```

Rust:

```rust
use inboxjot::{Event, Inboxjot};
use serde_json::json;

let client = Inboxjot::from_env()?;

client
    .events()
    .send(&Event {
        name: "order.completed".into(),
        email: "riti@example.com".into(),
        data: json!({ "order_id": "4821", "total": 49 })
            .as_object()
            .cloned()
            .unwrap_or_default(),
    })
    .await?;
```

Go:

```go
client := inboxjot.NewClient("")

result, err := client.Events.Send(ctx, inboxjot.SendEventParams{
	Name:  "order.completed",
	Email: "riti@example.com",
	Data:  map[string]any{"order_id": "4821", "total": 49},
})
```

Python:

```python
from inboxjot import Inboxjot

inboxjot = Inboxjot()

inboxjot.events.send(
    {
        "name": "order.completed",
        "email": "riti@example.com",
        "data": {"order_id": "4821", "total": 49},
    }
)
```

## Responses

| Status | Description |
| --- | --- |
| 202 | Accepted. Inboxjot records the event in the background. |
| 400 | A field is missing or invalid, or the Idempotency-Key header is not valid. |
| 401 | The API key is missing, revoked or expired. |
| 403 | The key is a Sending key or is limited to one domain, or the request comes from outside its IP allowlist. |
| 409 | A request with the same Idempotency-Key is still running. Retry after one second. |
| 413 | The body is larger than 2 MB. |
| 415 | The Content-Type header is not application/json. |
| 422 | The Idempotency-Key was already used with a different request. |
| 429 | Too many requests for this key. Wait for the seconds in the Retry-After header. |
| 500 | Something failed on our side. Retry later. |

202:

```json
{
  "contact_id": "con_06d2mfk8r9wq3zh5ka2pe"
}
```

400:

```json
{
  "name": "validation_error",
  "status": 400,
  "message": "Use letters, numbers, dots, dashes or underscores",
  "errors": [
    {
      "message": "Use letters, numbers, dots, dashes or underscores",
      "location": "name"
    }
  ],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

401:

```json
{
  "name": "unauthorized",
  "status": 401,
  "message": "Unauthorized",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

403:

```json
{
  "name": "forbidden",
  "status": 403,
  "message": "This key cannot be used from 203.0.113.7",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

409:

```json
{
  "name": "concurrent_idempotent_requests",
  "status": 409,
  "message": "A request with this idempotency key is still in progress. Try again later.",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

413:

```json
{
  "name": "payload_too_large",
  "status": 413,
  "message": "The request body is too large",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

415:

```json
{
  "name": "unsupported_media_type",
  "status": 415,
  "message": "The Content-Type must be application/json",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

422:

```json
{
  "name": "invalid_idempotent_request",
  "status": 422,
  "message": "This idempotency key was already used with a different request",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

429:

```json
{
  "name": "rate_limit_exceeded",
  "status": 429,
  "message": "Too many attempts. Try again later.",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

500:

```json
{
  "name": "unknown_error",
  "status": 500,
  "message": "Something went wrong. Please try again later.",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```