Skip to content

Automations ​

An automation is an event-triggered flow: something happens in your app, you send Sendgrail an event, and the automation runs a sequence of steps for the contact that event was about — send an email, wait, check a condition, update the contact, and so on. Where a broadcast is a single one-to-many send, an automation runs per contact, on its own timeline, as each one is triggered.

How it works ​

Every automation is a small graph: one trigger at the top, then steps connected below it. When the trigger event arrives for a contact, a run starts for that contact and walks the graph one step at a time until it reaches the end (or a step that ends it). Each run is bound to the contact the triggering event resolved to, so every step operates on that same contact.

A contact can only have one live run of a given automation at a time — a second trigger while a run is still in flight is ignored, so you won't double-send.

The trigger ​

An automation starts from a custom event. Define your events under Automations → Events (or let them be created on the fly the first time you send one), then pick one as the trigger. Fire it from your app:

bash
curl https://api.sendgrail.com/v1/events/send \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "event": "user.signed_up", "email": "ada@example.com" }'

The email resolves (or creates) the contact the run is for, and any extra properties you send with the event are available to later steps.

Steps ​

Build the flow on the canvas — click a node to add the next step. The available steps:

StepWhat it does
Send emailSends a published template from a verified domain, personalized from the contact and event.
WaitPauses the run for a duration (e.g. 2 days, 3h) before continuing.
Wait for eventPauses until another event arrives for the contact, or a timeout elapses — then branches down the Event received or Timed out path.
ConditionBranches Yes / No on the contact's fields or the event's properties.
Update contactSets a field or custom property, or subscribes/unsubscribes the contact.
Add to segmentAdds the contact to a segment.
Delete contactPermanently deletes the run's contact and ends the flow.

Steps that aren't ready show a warning marker on the canvas — a Send email step with no template, an Add to segment step with no segment chosen, and so on.

Turning it on ​

Click Start to run a pre-flight check. If anything is incomplete it lists each problem with a jump to the offending step; once the flow is clean it offers a slide-to-confirm to go live.

While an automation is enabled its graph is frozen — the structure can't change, so runs already in flight aren't disrupted. Rename it freely, but to edit the steps, disable it first. Re-enabling starts a clean run for the next matching event.

Run history ​

Open an automation and switch to Runs to see every contact that has gone through it. Each run carries a per-step breakdown — the status of each step (completed, waiting, failed), when it ran, and what it produced (a Send email step reports the email_id it sent). It's the same data the Retrieve an automation run endpoint returns, so you can inspect a run from the dashboard or the API.

From the API ​

Everything the editor does is available over the API — create the graph, enable it, and read run history:

Next steps ​

  • Events — define and fire the triggers.
  • Templates — the emails a Send email step delivers.
  • Audiences — the contacts, segments and properties steps read and write.

Transactional email on your own domain.