Create an automation

Build a workflow that runs when an event fires — a graph of steps a contact moves through.

POST /v1/automations

Requires a Full access API key — an automation can send mail and edit your audience, so a sending key embedded in an app cannot create one.

Body parameters

Parameter	Type	Required	Description
name	string	Yes	A name for the automation, for you — not shown to contacts. Max 120 characters.
status	string	No	enabled or disabled. Defaults to disabled — a new automation does not run until you turn it on.
steps	array	Conditional	The nodes of the graph. Must be sent together with connections.
connections	array	Conditional	The edges between steps. Must be sent together with steps.

steps and connections describe one graph and are validated as one — send both or neither. You can create an automation with just a name, then add the graph later with Update an automation.

Steps

A step is { key, type, config }. The key is yours — any string unique within the automation — and it's what connections refer to.

type	config	Does
trigger	event_name	Entry point. Starts a run when this event fires for a contact. An automation has exactly one.
send_email	template ({ id }), from, subject, optional reply_to	Sends a template to the contact.
delay	duration, e.g. "2 days"	Waits, then continues.
wait_for_event	event_name, optional timeout	Pauses until the contact fires this event, or timeout elapses.
condition	branch config	Splits the path — outgoing connections carry non-default type labels.
add_to_segment	segment_id	Adds the contact to a segment.
update_contact	field updates	Sets fields on the contact.

Connections

A connection is { from, to, type }, where from and to are step keys. type defaults to "default" — the single outgoing path of a normal step. A condition uses other type labels on its outgoing connections to mark which branch is which.

Example

A welcome series: when user.created fires, send the welcome template.

curl

curl -X POST 'https://api.sendgrail.com/v1/automations' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome series",
    "status": "disabled",
    "steps": [
      {
        "key": "start",
        "type": "trigger",
        "config": { "event_name": "user.created" }
      },
      {
        "key": "welcome",
        "type": "send_email",
        "config": {
          "template": { "id": "d3f8c2a1-6b47-4e9a-b25c-1f0e7a9d4c83" },
          "from": "Ada <ada@acme.com>",
          "reply_to": "support@acme.com",
          "subject": "Welcome to Acme"
        }
      }
    ],
    "connections": [
      { "from": "start", "to": "welcome", "type": "default" }
    ]
  }'

Node.js

const res = await fetch('https://api.sendgrail.com/v1/automations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Welcome series',
    status: 'disabled',
    steps: [
      {
        key: 'start',
        type: 'trigger',
        config: { event_name: 'user.created' },
      },
      {
        key: 'welcome',
        type: 'send_email',
        config: {
          template: { id: 'd3f8c2a1-6b47-4e9a-b25c-1f0e7a9d4c83' },
          from: 'Ada <ada@acme.com>',
          reply_to: 'support@acme.com',
          subject: 'Welcome to Acme',
        },
      },
    ],
    connections: [{ from: 'start', to: 'welcome', type: 'default' }],
  }),
});

const automation = await res.json();

Response

201, and the id of the automation:

{
  "object": "automation",
  "id": "auto_5PmT9wRx2AqK"
}

Ids are opaque, prefixed strings — auto_ here, run_ on a run. Fetch the full object, steps and connections included, with Retrieve an automation.

Enabling requires a complete graph

A disabled automation can be a work in progress — a half-built graph is fine to save. Enabling it, whether by creating with status: "enabled" or by updating it on, holds the graph to a higher bar:

• there is exactly one trigger step, and it names an event_name;
• at least one step follows the trigger;
• every step's config is filled in for its type — a send_email has a template, from and subject; a delay has a duration; an add_to_segment has a segment_id.

Fall short and enabling is a 422 that names what's missing. This is why the default is disabled: you build the graph, then flip it on once it holds together.

Once enabled, the graph is frozen — see Update an automation for how to change it (disable, edit, re-enable). To turn a running automation off, stop it.