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:

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:

Step	What it does
Send email	Sends a published template from a verified domain, personalized from the contact and event.
Wait	Pauses the run for a duration (e.g. 2 days, 3h) before continuing.
Wait for event	Pauses until another event arrives for the contact, or a timeout elapses — then branches down the Event received or Timed out path.
Condition	Branches Yes / No on the contact's fields or the event's properties.
Update contact	Sets a field or custom property, or subscribes/unsubscribes the contact.
Add to segment	Adds the contact to a segment.
Delete contact	Permanently 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:

• Create an automation
• Update · Stop · Delete
• List runs · Retrieve a run

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.