Create an event

Define an event your app can send — a named thing that happens to a contact, optionally with a shape its payload must fit.

POST /v1/events

Requires a Full access API key — defining an event is part of shaping how your audience is tracked, so a sending key embedded in an app cannot create one. Sending an event is the part a sending key can do.

Body parameters

Parameter	Type	Required	Description
name	string	Yes	The event name, a dotted identifier such as user.created. Max 120 characters. Cannot start with the reserved sendgrail. namespace — those names belong to events SendGrail emits itself.
schema	object | null	No	A flat map of field name → type describing the payload this event carries. Types are string, number, boolean, date. Omit it, or send null, for an event whose payload is unconstrained.

The schema is one level deep: values are type names, not nested objects. See The event object for how it is stored and read back.

Example

curl

curl -X POST 'https://api.sendgrail.com/v1/events' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "user.created",
    "schema": {
      "plan": "string",
      "seats": "number",
      "trial": "boolean",
      "signed_up_at": "date"
    }
  }'

Node.js

const res = await fetch('https://api.sendgrail.com/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'user.created',
    schema: {
      plan: 'string',
      seats: 'number',
      trial: 'boolean',
      signed_up_at: 'date',
    },
  }),
});

const event = await res.json();

Response

201, and the id of the event — nothing more:

{
  "object": "event",
  "id": "evt_3nBq7Ld2KeR9"
}

Ids are opaque, prefixed strings — an evt_ here, an auto_ on an automation, a run_ on a run. Treat them as strings; do not parse them.

Fetch the full object — including the stored schema — with Retrieve an event.

You don't have to create an event before sending it

Defining an event up front is optional. Send an event with a name that doesn't exist yet and SendGrail creates the event for you, with no schema. Creating it here first is how you attach a schema and document the shape your app promises to send — useful when an automation is going to key off it.

The schema is a promise, not a wall

A schema describes the payload an event is expected to carry. It is a flat map of field to type — the four types are string, number, boolean and date, and a date is an ISO 8601 string. Nested objects are not schema values; keep the shape one level deep.

The name is the identity, so it must be unique within your team — creating a second event called user.created is a 422. To change the shape later, don't recreate it; update the schema in place.