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.

This endpoint has two modes, chosen by the body. If the body contains any of contact_id, contactId or email, MailBlastr treats the request as an alias for POST /events/send and ingests an event instead of creating a definition — it then requires an event name — accepted as event, name, event_name or eventName — plus domain, counts against your automation-run quota, and returns an event object with contact_id and enrolled. The definition-create behaviour documented on this page applies only to bodies with none of those three keys.

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.