API Reference

Send Event

POST /events/send — send a custom event to trigger automations for a contact.

POST/events/send

Records a custom event for a contact and immediately enrolls that contact into every enabled automation belonging to the given `domain` whose trigger matches the event name. domain is required — every automation belongs to one of your sending domains, so the same event name (e.g. user.created) used across several products can never trigger another product's automations. The contact is identified by contact_id or email — you must supply exactly one. If an email is supplied and no matching contact exists in that domain's contacts, one is created automatically when the run starts; each domain keeps its own contact records, so unsubscribe state stays separate per domain.

Body parameters

eventstringrequired

The custom event name. Must not start with the reserved mailblastr: prefix.

domainstringrequired

The sending domain this event belongs to (one of your domains, e.g. yourdomain.com). Only automations belonging to this domain are triggered.

contact_idstringoptional

Identify the contact by id. Provide contact_id OR email.

emailstringoptional

Identify the contact by email address. Provide contact_id OR email. If no contact with this address exists in the domain's contacts, one is created when the run starts.

payloadobjectoptional

Optional. Arbitrary key-value data associated with the event. Must be an object (not an array). Fields become available as event.* variables in automation steps.

If an event definition with a schema exists for this event name, the payload is validated against it — fields that don't match the expected type are rejected with a 422 error and the event is not delivered.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.events.send({
  "event": "purchase.completed",
  "domain": "yourdomain.com",
  "email": "user@example.com",
  "payload": {
    "plan": "pro",
    "amount": 49
  }
});
console.log({ data, error });

Response

{
  "object": "event",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "event": "purchase.completed",
  "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "enrolled": 1
}

enrolled is the number of automations the contact was enrolled into as a result of this event. Errors: validation_error if event or domain is missing, the domain is not one of yours, or the event name uses the reserved prefix; 422 if the payload does not match the event definition's schema. See Errors.