API · Automations

Create Automation

Create an automation with one trigger and up to 100 execution steps (requires full access). Definitions are limited to 64 KiB and 12 levels of nesting; unsupported steps, options, cycles, and joins return 422.

POST/automationsFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`name` body · required	`string` At least 1 character	The name of the automation.
`status` body · optional	`"enabled" \| "disabled"`	Initial automation status, defaulting to disabled.
`steps` body · required	`(object)[]` 1–101 items	One trigger plus up to 100 execution steps, with a 64 KiB definition limit and maximum nesting depth of 12.
`steps[].key` body · required	`string`	A unique key for this step within the automation graph.
`steps[].type` body · required	`"trigger" \| "send_email" \| "delay" \| "wait_for_event" \| "condition" \| "contact_update" \| "contact_delete" \| "add_to_segment"`	Step type determining the required configuration: trigger, send_email, delay, wait_for_event, condition, contact_update, contact_delete, or add_to_segment.
`steps[].config` body · required	`object`	Step-specific settings such as event_name, template, duration, condition rules, contact fields, or segment_id; subject overrides, structured template variables, mixed nested conditions, null comparisons, and wait filter_rule return 422, and waits need a timeout of at most 30 days to activate.
`connections` body · required	`(object)[]`	Workflow connections forming a tree, without cycles, joins, or arbitrary fan-out.
`connections[].from` body · required	`string`	The `key` of the source step.
`connections[].to` body · required	`string`	The `key` of the target step.
`connections[].type` body · optional	`"default" \| "condition_met" \| "condition_not_met" \| "timeout" \| "event_received"`	Connection type, defaulting to default.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/automations" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Welcome","steps":[{"key":"start","type":"trigger","config":{"event_name":"user.created"}},{"key":"pause","type":"delay","config":{"duration":"1 hour"}}],"connections":[{"from":"start","to":"pause"}]}'

Response

201 · application/json. Example IDs stand for IDs returned by your installation.

json

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

Behavior and errors

New automations default to disabled. The SDK uses eventName; the HTTP body uses event_name. One trigger and up to 100 execution steps are allowed. See automations for graph limits and supported options.

Use a full-access credential. Unknown or foreign resources return 404. See authentication, errors, rate limits, and pagination.