Define a multi-step sequence as a draft; nothing is sent until it is activated, from the dashboard or with set_automation_status. Unlike several separately scheduled emails, it ends on its own when the person unsubscribes, replies, bounces, opts out of its topic, or their tags say so. identity_id must be a marketing sending domain (see list_sending_domains; risk_class 'marketing') and from must sit on it; both are checked here rather than at the first send. reply_to sends replies somewhere other than from, and it disables the reply exit: SendRaven never sees mail sent to another domain. Every reference is checked now rather than at the first enrolment: an unknown topic_key (422 unknown_topic), a template_slug that does not exist, or a step with neither html nor template_slug is refused with 422 invalid_request, a from with no verified marketing domain answers 422 no_verified_identity, and a slug already in use in this workspace answers 409 conflict; list_automations shows the existing automation with that slug. reenrollment decides whether someone whose enrolment ended can be enrolled again: 'after_completion' (the default) allows it, 'never' enrols each person once. When one audience holds everyone, a contact_added trigger mails every new contact, while a tag_added trigger on a product's tag reaches only that product's people.
View input schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"slug": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"description": "Lowercase letters, digits and hyphens"
},
"identity_id": {
"type": "string",
"description": "A marketing sending domain's id from list_sending_domains (a UUID), not the domain name"
},
"from": {
"type": "string",
"minLength": 3,
"description": "On the identity's domain, e.g. 'Ana <ana@news.example.com>'"
},
"reply_to": {
"type": "string",
"description": "Where replies go instead of from, e.g. the founder's own inbox. SendRaven receives mail for its own domains only, so with a reply-to elsewhere a reply cannot stop the sequence, however exit_on_reply is set"
},
"trigger": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"api",
"contact_added",
"event",
"tag_added",
"date"
],
"description": "api: enrol with enroll_in_automation. contact_added: starts when someone joins audience_id. event: starts on emit_event with event_name. tag_added: starts when a contact gains tag (tag_contact, or a contact added carrying it); a contact that already had the tag starts nothing, so turning it on does not mail everyone tagged. date: starts for each contact in audience_id on the day (UTC) their date_attribute plus offset_days comes round, once per date; activating it never mails dates already passed or already inside the offset window, only those due from that day on"
},
"audience_id": {
"type": "string",
"description": "Required for contact_added and date; the audience's id, not its name"
},
"event_name": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "Required for event, e.g. trial_started. Up to 120 characters, matched exactly"
},
"tag": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Required for tag_added, e.g. audio-player. Normalised like contact tags"
},
"date_attribute": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 100,
"description": "Required for date: the contact attribute holding a YYYY-MM-DD date or ISO timestamp, e.g. renewal_date or birthday. Contacts whose value is in any other format are skipped"
},
"offset_days": {
"type": "integer",
"minimum": -365,
"maximum": 365,
"description": "For date: days from the date, negative for before (-7 is a week before a renewal). Defaults to 0"
},
"recurring_yearly": {
"type": "boolean",
"description": "For date: fire on every anniversary (birthdays, yearly renewals) rather than once. Defaults to false"
}
},
"required": [
"kind"
],
"additionalProperties": false
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,40}$",
"description": "The step's stable id. On create, optional (generated when left out). On update_automation, pass back the id get_automation returned for every step you keep, or the people on it lose their place; leave it out only for a new step. An id the automation does not have is refused"
},
"delay_minutes": {
"type": "integer",
"minimum": 0,
"maximum": 525600,
"description": "From enrolment for the first step, from the previous step for the rest. At most 525600 (one year)"
},
"subject": {
"type": "string",
"minLength": 1,
"maxLength": 998
},
"html": {
"type": "string",
"description": "Inline body; template_slug is the alternative. One of the two is required"
},
"template_slug": {
"type": "string",
"minLength": 1,
"description": "A template from list_templates, rendered with the enrolment's variables. Must already exist"
},
"condition": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"has_tag",
"lacks_tag",
"engaged",
"not_engaged",
"attribute_equals"
],
"description": "has_tag / lacks_tag: the contact carries tag. engaged / not_engaged: the person opened or clicked anything this sequence has sent them so far, scanners excluded; not allowed on the first step. attribute_equals: the contact attribute key equals value, compared as text"
},
"tag": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Required for has_tag and lacks_tag"
},
"key": {
"type": "string",
"pattern": "^[a-zA-Z0-9_]+$",
"maxLength": 100,
"description": "Required for attribute_equals"
},
"value": {
"type": [
"string",
"number",
"boolean"
],
"description": "Required for attribute_equals"
}
},
"required": [
"type"
],
"additionalProperties": false,
"description": "One yes/no question asked when the step comes due. False skips the step (nothing sent) and the person moves on to the next one. The usual one: lacks_tag customer on an upgrade pitch"
},
{
"type": "null"
}
],
"description": "One yes/no question asked when the step comes due. False skips the step (nothing sent) and the person moves on to the next one. The usual one: lacks_tag customer on an upgrade pitch"
}
},
"required": [
"delay_minutes",
"subject"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20
},
"topic_key": {
"type": "string",
"minLength": 1,
"description": "Send every step under this topic (see list_topics). Its unsubscribe link then opts the person out of this kind of mail only, and opting out ends the sequence. Must be an existing topic's key; an unknown one is refused with 422 unknown_topic"
},
"exit_tags": {
"type": "array",
"items": {
"$ref": "#/properties/steps/items/properties/condition/anyOf/0/properties/tag"
},
"maxItems": 20,
"description": "Contact tags that end the sequence: nobody carrying one is enrolled, and adding one ends the enrolment. A trial sequence with exit tag 'customer' stops for someone tagged 'customer' when they upgrade"
},
"required_tags": {
"type": "array",
"items": {
"$ref": "#/properties/steps/items/properties/condition/anyOf/0/properties/tag"
},
"maxItems": 20,
"description": "Tags a person must keep: only people carrying all of them are enrolled, and removing one ends the enrolment. Someone with no contact record has no tags, so is never enrolled"
},
"exit_on_reply": {
"type": "boolean",
"description": "End the enrolment when the person replies. Defaults to true; false suits dunning"
},
"reenrollment": {
"type": "string",
"enum": [
"after_completion",
"never"
],
"description": "after_completion (the default): someone whose enrolment completed or was cancelled can be enrolled again. never: each person goes through it once, and a later enrolment answers enrolled: false with reason previously_enrolled. never suits onboarding or a one-time offer, where a second run would mail someone the same sequence twice"
},
"default_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Template values every enrolment gets, under the variables an enrolment passes (which win). Required for contact_added and tag_added, which enrol with no values: every placeholder in the steps' subjects, html and templates needs one here, or the call answers 422 missing_variables naming the missing ones. Read at each step, so a fix reaches people already enrolled"
}
},
"required": [
"name",
"slug",
"identity_id",
"from",
"trigger",
"steps"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}