Update an automation

Rename an automation, turn it on or off, or replace its graph.

PATCH /v1/automations/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The automation id (auto_…).

Body parameters

Send only what you want to change.

Parameter	Type	Required	Description
name	string	No	A new name. Max 120 characters.
status	string	No	enabled or disabled. Enabling holds the graph to the completeness rules.
steps	array	Conditional	Replaces the graph's nodes. Must be sent together with connections.
connections	array	Conditional	Replaces the graph's edges. Must be sent together with steps.

steps and connections are one graph — send both or neither. Sending them replaces the whole graph, it does not merge into the existing one.

Example

Add a two-day delay and a follow-up to the welcome series, then leave it disabled to re-enable once you're happy.

curl

curl -X PATCH "https://api.sendgrail.com/v1/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome series v2",
    "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>",
          "subject": "Welcome to Acme"
        }
      },
      { "key": "wait", "type": "delay", "config": { "duration": "2 days" } },
      {
        "key": "tips",
        "type": "send_email",
        "config": {
          "template": { "id": "9a2f7c4e-1b0d-4e33-8e10-3f1c9a52d0e4" },
          "from": "Ada <ada@acme.com>",
          "subject": "Getting the most out of Acme"
        }
      }
    ],
    "connections": [
      { "from": "start", "to": "welcome", "type": "default" },
      { "from": "welcome", "to": "wait", "type": "default" },
      { "from": "wait", "to": "tips", "type": "default" }
    ]
  }'

Node.js

const res = await fetch(`https://api.sendgrail.com/v1/automations/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Welcome series v2',
    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>',
          subject: 'Welcome to Acme',
        },
      },
      { key: 'wait', type: 'delay', config: { duration: '2 days' } },
      {
        key: 'tips',
        type: 'send_email',
        config: {
          template: { id: '9a2f7c4e-1b0d-4e33-8e10-3f1c9a52d0e4' },
          from: 'Ada <ada@acme.com>',
          subject: 'Getting the most out of Acme',
        },
      },
    ],
    connections: [
      { from: 'start', to: 'welcome', type: 'default' },
      { from: 'welcome', to: 'wait', type: 'default' },
      { from: 'wait', to: 'tips', type: 'default' },
    ],
  }),
});

const automation = await res.json();

Response

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

Fetch the updated object with Retrieve an automation.

An enabled automation's graph is frozen

While an automation is enabled, contacts may be part-way through it — a run paused on a delay, another waiting on a wait_for_event. Editing the graph underneath them would leave those runs pointing at steps that no longer exist. So the graph of an enabled automation is frozen: send steps/connections to an enabled automation and you get a 409.

To change a live automation, disable it first:

1. PATCH with { "status": "disabled" } — or stop it.
2. PATCH the new steps and connections.
3. PATCH with { "status": "enabled" } once the graph is complete.

name and status are not frozen — you can rename or toggle an enabled automation freely. It is only the shape of the graph that's held still while it runs. Enabling still requires the complete graph, so a partial edit left half-done stays disabled until you finish it.