What is newsletter automation?

Emails that send themselves when something happens to a subscriber, such as joining, getting a tag, buying a product or reaching a date, instead of when you send an issue by hand.

What can start a FlockStack automation?

15 things: a subscriber joining (once confirmed, if the newsletter asks for it), a tag added or removed, a contact joining or leaving a segment, a date field's day, a custom field changing, a reader upgrading or downgrading, a product bought, a referral credited, a stretch without opens, a click on a link, contacts you add by hand, or your own code.

Can I automate from my own app?

Yes, by feeding automations. Your code signs people up, adds tags, sets date fields or enrolls contacts directly through the API, and the automations that trigger on those start. The sending runs inside FlockStack.

Can an AI assistant build and run an automation?

Yes. Through the MCP server an assistant can draft one, build the segments it needs and read its report. Activating is marked as an action that can't be undone, and assistants are told to show you the trigger and emails first.

How many automations can I have?

The Free plan has 2. Paid plans can have up to 50 a newsletter, with up to 20 steps in a list, 60 in all, and waits from a minute to 365 days.

Automation

Newsletter automation software with API and MCP access

Newsletter automation means emails that send themselves when something happens to a subscriber. FlockStack's automations start from a signup, a tag, a segment, a purchase, a date and more, then run emails, waits, tag and field changes, webhooks, branches and random splits for each contact. You build them in the dashboard, through the REST API or with an AI assistant, and each email follows the same sending rules as a campaign.

Start with FlockStack

15 triggersA signup, a tag, a segment, a field, a purchase, an upgrade, a link click, a date, a stretch without opens, or your own code. Each contact starts on their own timeline.
Branches and splitsUp to 20 steps in a list, paths nested 3 deep: send different emails to paid readers, or split contacts at random.
Scheduled issuesSchedule any campaign up to a year ahead, and take it back to a draft whenever you like.
API and MCPCreate and manage them from code or an assistant. Activating asks for your confirmation.

A newsletter automation sends email because of what a subscriber did or when something is due, not because you pressed send on an issue. The common cases are a welcome series for new subscribers, a follow-up after someone is tagged or buys, a reminder before a date such as a renewal or a birthday, and re-engagement for readers who went quiet.

FlockStack has this built in. It is separate from what the API and the MCP server do, which is covered below.

What a FlockStack automation is

An automation does things for each contact it starts for. One trigger starts it; the steps then run in order for that contact, each on their own timeline. create_automation makes a draft, and nothing is sent until activate_automation. You can also start from a template: a welcome series, re-engagement, paid onboarding, a thank-you to product buyers or to referrers.

Triggers

Trigger	Starts when	When it's noticed
`subscribed`	A contact joins. With confirmed opt-in, that is once they confirm. Optionally only with a tag, or from a source such as `website` or `api`	At signup
`tag_added`, `tag_removed`	A contact gets or loses a tag	When the tag changes
`segment_joined`, `segment_left`	A contact starts or stops matching a segment	About every 60 minutes
`date_field`	The day of a contact's date field, plus or minus a number of days, once or every year	Once a day
`field_changed`	A custom field gets a new value	When the field changes
`upgraded`, `downgraded`	A reader starts or stops paying for the paid tier	When the payment changes
`product_bought`	A reader buys any product, or one you pick	At purchase
`referral_credited`	A referral is credited, each time or when the referrer reaches a number	When it is credited
`unengaged`	A contact has had no opens or clicks for a number of days	Once a day
`link_clicked`	A contact's first click on a link you name, in any issue or one	At the click
`manual`, `api`	You add contacts on the automation's page, or your code enrolls them	When you add them

A contact enters an automation once, except for purchases, referral credits, upgrades, downgrades and leaving a segment, which start it again each time. Only an active contact can enter, and importing contacts doesn't start automations.

Steps

Step	What it does
`email`	Sends an email with a subject, preview text and a body in Markdown, rich text or HTML. Merge tags such as `{{first_name}}` are filled in for each contact
`wait`	Holds the contact for minutes, hours or days (up to 365), until a date and time, or until a weekday at a time in a time zone
`add_tag`, `remove_tag`	Changes the contact's tags, which can start other automations or move them in or out of segments
`set_field`	Sets a custom field to a value, or clears it
`webhook`	Sends an `automation.step` event to your webhook endpoints, with the step's name
`branch`	Sends contacts who match a condition down one path and everyone else down the other, judged when they reach the step
`split`	Splits contacts at random into 2 to 5 paths by percentage. A contact takes the same path every time
`move`	Starts another automation of the newsletter for the contact, and ends this one
`end`	Finishes the contact's run

Branch and split paths hold steps of their own, nest 3 lists deep, and do not join again. A list holds up to 20 steps, and an automation up to 60 in all.

Subscriber workflows

Automations work on what FlockStack knows about each contact:

Tags, up to 30 on a contact. Tag people by how they joined, what they bought or what they asked for.
Custom fields (text, number, date and more), up to 20 a newsletter, which feed merge tags, segments and the date trigger.
Segments, up to 50 a newsletter, built from 13 kinds of condition, among them status, tags, fields, signup dates, source, whether someone opened or clicked lately, free or paid, country and poll answers. A branch uses the same conditions.

A contact leaves an automation as soon as they unsubscribe, bounce, complain, are suppressed or deleted, and so does one who isn't active when a step runs.

Examples

A welcome series that treats paid readers differently:

Welcome series

{
  "name": "Welcome series",
  "trigger": { "type": "subscribed" },
  "steps": [
    { "type": "email", "subject": "Welcome", "content": "Thanks for joining, {{first_name|friend}}." },
    { "type": "wait", "amount": 2, "unit": "days" },
    {
      "type": "branch",
      "condition": { "match": "all", "conditions": [{ "type": "tier", "value": "paid" }] },
      "paths": [
        { "steps": [{ "type": "add_tag", "tag": "paid-welcomed" }] },
        {
          "steps": [
            { "type": "email", "subject": "Where to start", "content": "Here are three issues worth your time." },
            { "type": "wait", "weekday": "friday", "time": "09:00", "timeZone": "Europe/Paris" },
            { "type": "add_tag", "tag": "onboarded" }
          ]
        }
      ]
    }
  ]
}

A reminder a week before a renewal, every year. First define the date field, then the automation that reads it:

Date field

{ "label": "Renewal date", "type": "date" }

Renewal reminder

{
  "name": "Renewal reminder",
  "trigger": { "type": "date_field", "field": "renewal_date", "offsetDays": -7, "repeat": "yearly" },
  "steps": [{ "type": "email", "subject": "Your renewal is next week", "content": "A short note before your renewal, with what changed this year." }]
}

A follow-up that starts when your product adds the tag trial-ended:

After a trial ends

{
  "name": "After a trial ends",
  "trigger": { "type": "tag_added", "tag": "trial-ended" },
  "steps": [
    { "type": "email", "subject": "How did the trial go?", "content": "Reply to this email with what you'd change." },
    { "type": "wait", "amount": 3, "unit": "days" },
    { "type": "email", "subject": "Still thinking it over?", "content": "Here is what the paid plan adds." },
    { "type": "add_tag", "tag": "trial-followed-up" }
  ]
}

Scheduling is for issues, apart from automations. schedule_campaign sends a draft at a time within a year, and unschedule_campaign turns it back into a draft. A scheduled campaign stays editable until it goes out. The plan's limits and the pre-send checks run when you schedule it and again when it goes out.

A large send can go out in steps: send_campaign_to_more sends a sent issue to contacts who haven't received it yet, most engaged first. For issues made from a feed's new items on a schedule, FlockStack has series (create_series), which make a draft to review or send it, once for each slot.

Automating from your own code

The API doesn't run automations itself. They run inside FlockStack. What the API does is create and manage them, and feed them with what happens in your product:

Sign someone up with POST /api/v1/contacts. A source and tags in the request can match a subscribed trigger, or fire a tag_added one.
Add a tag when something happens in your product with POST /api/v1/contacts/{id}/tags. A tag_added automation starts for that contact.
Set a date field with PATCH /api/v1/contacts/{id}/fields for a date_field trigger to act on.
Enroll contacts directly into an automation with the api trigger and enroll_contacts, up to 100 addresses a call.
Run the automation with POST /api/v1/automations, POST /api/v1/automations/{id}/activate and POST /api/v1/automations/{id}/pause, and read results with GET /api/v1/automations/{id}/report.

Terminal

curl -X POST "https://flockstack.io/api/v1/contacts/6650f1c2e9b1d4a012345678/tags" \
  -H "Authorization: Bearer $FLOCKSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"trial-ended"}'

Every automation operation the dashboard has is also in the API: the newsletter API describes its keys and limits.

Automation with an AI assistant

Connect an assistant through the newsletter MCP server and it gets the same actions as tools. It can draft an automation, build a segment, schedule an issue and read a report. It can't skip the safety steps: activate_automation is marked as an action that can't be undone, the server asks assistants to show you the trigger and each email before activating, and most clients ask for your approval.

Things you can ask:

"Draft a three-email welcome series for people who join from my website, and show it to me before activating it."
"Make a segment of readers who haven't opened anything in 90 days and tell me how many there are."
"Pause the renewal reminder."
"Schedule the draft for Thursday at 9 and send me a test first."

Approval and safety controls

Activating checks every email first, and it can't be undone once emails go out. pause_automation stops it at any time, and contacts continue where they were when it is activated again.
Automation emails go through the sending path of a campaign: an unsubscribe link and one-click headers, suppression, the plan's emails, the send rate and the account's blocks.
When the month's emails are used up, automation emails wait until they reset.
On FlockStack Cloud, an account's automations share a daily room that grows with the volume the account has proven, and starts at no less than 500 emails.

Where it stops

Paths don't join again. A branch or a split sends each contact down one path to its end.
An active automation is fixed. Pause it to change its trigger or its steps.
Imports don't start them, and an imported contact gets no welcome series.
The Free plan has 2 automations, besides the welcome email. A paid plan lifts that to 50 a newsletter.

The audiences guide in the docs is the full reference for triggers, steps, segments, tags and merge tags.

Questions

What is newsletter automation?: Emails that send themselves when something happens to a subscriber, such as joining, getting a tag, buying a product or reaching a date, instead of when you send an issue by hand.
What can start a FlockStack automation?: 15 things: a subscriber joining (once confirmed, if the newsletter asks for it), a tag added or removed, a contact joining or leaving a segment, a date field's day, a custom field changing, a reader upgrading or downgrading, a product bought, a referral credited, a stretch without opens, a click on a link, contacts you add by hand, or your own code.
Can I automate from my own app?: Yes, by feeding automations. Your code signs people up, adds tags, sets date fields or enrolls contacts directly through the API, and the automations that trigger on those start. The sending runs inside FlockStack.
Can an AI assistant build and run an automation?: Yes. Through the MCP server an assistant can draft one, build the segments it needs and read its report. Activating is marked as an action that can't be undone, and assistants are told to show you the trigger and emails first.
Does an automation email someone who unsubscribed?: No. A contact leaves an automation when they unsubscribe, bounce, complain, are suppressed or deleted, and the status is checked again before each step.
How many automations can I have?: The Free plan has 2. Paid plans can have up to 50 a newsletter, with up to 20 steps in a list, 60 in all, and waits from a minute to 365 days.

Build your first automation

Create your account, then set up a welcome series from a template on the Automations page or ask your assistant to draft it.