Skip to content

Update an event ​

Replace an event's schema — tighten the shape its payload must fit, or clear it.

http
PATCH /v1/events/{id}

Requires a Full access API key.

Path parameters ​

ParameterTypeRequiredDescription
idstringYesThe event id (evt_…) or the event name.

Body parameters ​

ParameterTypeRequiredDescription
schemaobject | nullYesThe schema to replace the current one with — a flat map of field → type (string, number, boolean, date). Send null to clear the schema and accept any payload.

schema replaces, it does not merge — send the whole map you want, not just the fields that changed. The event's name is its identity and cannot be changed; create a new event instead.

Example ​

bash
curl -X PATCH "https://api.sendgrail.com/v1/events/user.created" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "schema": {
      "plan": "string",
      "seats": "number",
      "referrer": "string"
    }
  }'
js
const res = await fetch('https://api.sendgrail.com/v1/events/user.created', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    schema: {
      plan: 'string',
      seats: 'number',
      referrer: 'string',
    },
  }),
});

const event = await res.json();

Response ​

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

Fetch the updated object with Retrieve an event.

Replace, not merge ​

The schema you send becomes the whole schema. To add one field, send the existing fields plus the new one; send only the new field and the others are gone. This is the same "send the full value" rule that keeps an update predictable — what you PATCH is what the event ends up with.

Send "schema": null to remove the schema entirely. The event then accepts any payload again, exactly as an event created without one does.

Changing the shape doesn't rewrite the past ​

Updating the schema changes what future sends are validated against. Events already recorded keep the payloads they were sent with — a tightened schema is not applied retroactively, so nothing you've already collected is invalidated or discarded.

Transactional email on your own domain.