Core

Events

Record discrete in-product actions. Any event you send can trigger a Meisa automation, so events are how you react to what users do, not just who they are.

Track an event

POST/events/track/scope: events:track

Records a custom event against an existing contact. The contact must already exist — upsert them first. A tracked event fires any automation whose trigger is a matching custom event.

Field	Type	Description
`event_name`required	string	The event identifier, e.g. `feature_activated` or `completed_onboarding`.
`email`	string	The contact's email. Required unless you send `external_id`.
`external_id`	string	Your user ID. Required unless you send `email`. Matched before email.
`properties`	object	Optional metadata about the event (anything you want available to automations and the activity log).

Example

track an event

curl -X POST "https://api.meisa.io/api/v1/events/track/" \
  -H "X-API-Key: meisa_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "event_name": "feature_activated",
    "properties": { "feature": "export", "plan": "pro" }
  }'

response

{
  "status": "tracked",
  "contact_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_name": "feature_activated",
  "timestamp": "2026-06-02T12:00:00Z"
}

A 404 means no contact matched the email/external_id — upsert the contact first.

Events vs. fields

When to use an event vs. a custom field

Use a custom field (via upsert) for ongoing state you'd want to filter on later — plan, signin_count, onboarding_completed. Use an event for a moment in time you want to react to — feature_activated, hit_usage_limit, invited_teammate. Many integrations only ever need upsert; reach for events when you want an automation to fire on a specific action.

PreviousContacts & upsert NextTags