Start A Campaign From A Trigger

Some of the moments worth an email never happen in a browser: a card is declined, a trial is about to end, an export finishes. A trigger names one of those moments. Each time it happens your product's backend sends Behavly an event for the person, and a Trigger Campaign that starts on that trigger takes them in the moment it arrives.

Make The Trigger

1. 1Open Triggers in the left menu, under Campaigns, and click New trigger. You can also make one while you build: a new Trigger Campaign offers New trigger when it opens, and so does its Who enters step.
2. 2Give it a Name, like Payment failed. The Key follows it (payment_failed): it is what your code sends, and it can't change once the trigger exists.
3. 3Under Payload, list the details each event carries, each with a type (text, number, yes/no, date or list) and whether it is required. Or paste an example under Example JSON and choose Apply to fields.
4. 4Click Create trigger. Behavly shows the request that sends it, in cURL, JavaScript or Python.
5. 5On the trigger's page, Create an Agent opens a new Trigger Campaign that already starts on it.

The person is always email. It is not a payload field, and an event without it is refused.

Send It From Your Server

Create an API key with Send events only access in Settings → Account & Settings → API. That key can send events and nothing else, so if it ever leaks it cannot read your contacts or change anything. Keep it on your server and send each event to send_event:

curl -X POST 'https://behavly.io/api/v1/send_event' \
  -H "Authorization: Bearer $BEHAVLY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"event":"payment_failed","email":"ana@example.com","properties":{"plan":"Pro","amount":49}}'

event

The event's key. Required.

email

The person it is about. Required.

properties

The details, as JSON. At most 50 keys and 8 KB. A described event's required fields must be there, with the right types.

occurred_at

When it happened. Optional; defaults to now, and can be up to 30 days ago.

idempotency_key

Your own id for the event. Send it when you retry: the same key twice is one event, counted once.

The answer names each campaign the event started, and why any did not: the person is already on the path, already went through it, unsubscribed or bounced, or the campaign is paused. To send many at once, send_events takes up to 100 in one request.

Try It Without Code

Every trigger's page has Send a test event. It sends the event now for the address you enter, with example details, exactly as your server would: an active Trigger Campaign that starts on it takes that person in and its emails are real. Test events are not counted against your plan; a workspace can send 30 an hour.

What Happens When One Arrives

• Every active Trigger Campaign that starts on the trigger takes the person in at once. Someone already on the path is left alone, and events from before the campaign was active don't count.
• The usual rules still apply: the sending window, the frequency cap, review before sending, unsubscribes and bounces. An event that arrives at night starts the path, and the first email waits for the window.
• With Re-entry on, someone who finished the path can go round again on a later event, 90 days or more after leaving, never after a reply or an unsubscribe.
• People already on any path who wait for, branch on or aim for that trigger (a wait, a branch, the goal or skip if done) move on right away.

Each trigger's page lists the last 25 events received, with the details each carried and what it did. That is the place to look when a trigger seems to do nothing.

Triggers You Didn't Make

An event with a key Behavly has not seen is still accepted. Its trigger appears in Triggers as not described yet, with fields read from the first event, so you can check them and save.

Limits

Trigger Campaigns are on Starter and above. Each active one holds one of your plan's always-on campaign slots, like an Always-on Pattern Campaign.

Events from your server count toward your plan's product events each month: 1,000 on Free, 25,000 on Starter, 250,000 on Growth and 1,000,000 on Scale. Events from your website snippet don't count. When the month's allowance is spent, the API answers 402 with a link to upgrade. Each key can make 120 requests a minute.