API Reference

Create Event

POST /events — create a custom event definition, optionally with a payload schema.

POST/events

Creates a custom event definition. If a schema is defined, payloads are validated when the event is sent — fields that don't match the expected type are rejected with a 422 error and the event is not delivered.

Body parameters

namestringrequired

The name of the custom event. Can be any string (e.g. user.created, welcome, my-custom-event) — dot notation is a recommended convention but is not required. Must not start with the reserved mailblastr: prefix.

schemaobjectoptional

An optional schema definition for the event payload. Must be an object with flat key/type pairs. Supported types: string, number, boolean, date.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.events.create({
  "name": "user.created",
  "schema": {
    "plan": "string"
  }
});
console.log({ data, error });

Response

Returns the created event definition (HTTP 201).

{
  "object": "event",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "name": "user.created",
  "schema": {
    "plan": "string"
  },
  "created_at": "2026-06-23T10:00:00.000Z",
  "updated_at": "2026-06-23T10:00:00.000Z"
}

Errors: validation_error if name is missing, uses the reserved prefix, or an event definition with the same name already exists. See Errors.