API reference

The dashboard's overview for one newsletter: subscribers each day of the last 30 days, email results of the last 30 days against the 30 before, emails sent per hour today and yesterday, and the plan's usage this month, which the account's newsletters share.

Lists the account's newsletters, 3 at most, first created first, with their settings and active contacts. Actions that take a newsletter use the first one when it's left out.

Gets a newsletter's settings: sender, postal address, welcome and confirmation emails, list cleanup and archive.

Creates a newsletter. An account has up to 3, sharing its plan's emails and subscribers; one more answers conflict. Without a fromEmail it sends from the shared address hello@<slug>.<shared domain>, which FlockStack sets up in a few minutes. List cleanup is on unless cleanup.enabled is false. Without a postalAddress, its emails print the server's default if it has one: FlockStack's address on FlockStack Cloud.

Changes a newsletter's settings. Send only the fields to change; nested groups (welcome, confirmation, cleanup, author) keep the fields you leave out. An account changes slugs 3 times a day at most: one more answers rate_limited.

Says whether a newsletter can take a slug: available, or taken by another newsletter, reserved by FlockStack or invalid, with the message saving it would answer. Checking doesn't count toward the 3 slug changes a day.

Sends the saved welcome email to the account owner's address, switched on or not. It counts toward the plan's emails.

Lists campaigns, newest activity first: sent issues by send date, scheduled ones by send time, drafts by last edit. Content is left out; get_campaign has it.

Gets a campaign with its content, stats and, for drafts, what would block sending it now.

Delivery, open, click, bounce, complaint and unsubscribe rates of a sent campaign, its list cleanup emails, results by inbox provider, and how many contacts a capped send hasn't reached yet.

Creates a draft. Nothing is sent: review it in the dashboard or with get_campaign, then send_test_email, schedule_campaign or send_campaign.

Changes a draft or scheduled campaign's subject, preview text, content, audience or segment. Send only the fields to change; format goes with content. Sent campaigns can't change.

Deletes a draft or scheduled campaign: it leaves every list and a scheduled send never goes out. Sent campaigns can't be deleted.

Copies a campaign's subject, preview text, content and segment into a new draft.

Sends the campaign as saved to the account owner's address, subject prefixed with [Test]. Nobody else gets it. It counts toward the plan's emails.

Schedules a draft to send by itself at a time within a year. It goes out without asking again, unless unschedule_campaign runs first. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. Plan limits and pre-send checks run now and again when it goes out. FlockStack Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked.

Turns a scheduled campaign back into a draft, so it doesn't go out.

Sends a draft or scheduled campaign now to the newsletter's active contacts, to the campaign's segment (update_campaign) or to its free or paid readers only (audience), most engaged first. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. A campaign that is already sending or sent answers conflict, so a retry never sends twice. Plan limits, the from address, the postal address and the email size are checked first. FlockStack Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked.

Sends a sent campaign to contacts who haven't received it yet, the next most engaged first: a send in steps. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. Each call starts a new step, so check get_campaign_report before calling it again; while a step is still sending it answers conflict. FlockStack Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked.

Stops a campaign that is sending. Emails already sent stay sent; the rest wait until resume_campaign.

Sends the rest of a paused campaign. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. The plan limits and the account's state are checked again first. Resumed after a high_rates or first_send_slice pause, only the block level stops it again.

Changes the path of a campaign's archive page (/p/<slug>), or pins a sent issue to the top of the archive. Works on sent campaigns too.

Counts what the newsletter's list cleanup would do if the campaign went out now: issues sent, last-chance emails instead, contacts still waiting to answer one, and contacts made dormant. Reads the whole list, so it can take a few seconds.

Counts the contacts a send of the campaign would reach if it went out now, and shows the first few: the active contacts of its audience (all, free or paid) that are in its segment, or all the newsletter's, with suppressed addresses out. It also counts the emails it would use from the plan (the list cleanup's last-chance emails included) and whether they fit. Reads the whole list when the list cleanup is on, so it can take a few seconds.

Lists contacts, newest signups first, 50 a page. Filter by newsletter, status, tag or the start of the email address; pass nextCursor back as cursor for the next page. counts has every status for the same filters.

Gets one contact by ID or email address, with its status, dates and engagement.

Signs someone up, like the archive's form: they get the welcome email, or the confirmation email when the newsletter asks new subscribers to confirm. Signing up again keeps the contact as it is unless resubscribe is true, but its tags and fields are added to and set. Works with signups only keys, for website forms. Signups and confirmation emails keep coming in over the plan's limits; welcome emails count toward the month's emails and are skipped once they're used up, never sent later (get_billing's usage.welcomeEmailsPaused). A misspelled domain (gmial.com) answers validation_failed with the address it was likely meant to be; spam trap addresses, domains that can't receive email, and addresses FlockStack knows can't receive email (they hard bounced or hit a spam trap, from any sender on FlockStack) answer validation_failed too.

unsubscribed stops all emails to the contact, for good: only the person signing up again brings them back. active brings back a dormant contact; unsubscribes, bounces and complaints are final.

Deletes a contact from its newsletter, with its dates and engagement. It can't be undone. For a contact who unsubscribed, bounced or complained, FlockStack keeps a hash of the address so the newsletter never emails it again: import_contacts leaves it out, and add_contact or a signup form adds it back with that status. Any other contact can be added again like a new one.

Adds up to 1000 contacts per call, with the same checks as the dashboard's CSV import: invalid, misspelled (gmial.com…), spam trap, role (info@, support@…), throwaway, duplicate and suppressed addresses, undeliverable ones (FlockStack knows they can't receive email: they hard bounced or hit a spam trap, from any sender on FlockStack), and addresses on domains that can't receive email, are left out and counted. consent must be true: "These people agreed to receive my emails". Existing contacts keep their status unless a row gives a stricter one (unsubscribed, bounced, complained), which is final. No welcome emails go out. Rows can carry tags and custom field values, and tags adds tags to every contact in the call. For more rows, send the next chunk with the importId of the first.

Makes a CSV download link for the contacts matching the filters, valid for an hour, no API key needed to open it. The columns go back in through the import as they are.

Gets a newsletter's referral program: whether it is on, its rewards, and how many referrals counted. Every subscriber has a link of their own to your website. A referral counts for the subscriber who shared it once the new subscriber confirms their address, and rewards unlock at the numbers you set.

Turns a newsletter's referral program on or off and sets its rewards. Send only what changes; rewards replaces the whole list. A reward is a title, the number of referrals that unlocks it (1 to 10000) and a link or a message, revealed on the subscriber's referral page and sent in an email through the usual sending path, with its unsubscribe link, counted toward the month's emails. Up to 10 rewards. The program needs the newsletter's confirmation emails and website on: referral links lead to the website's signup form, and a referral counts once the new subscriber confirms. Put {{referral_link}} and {{referral_count}} in an issue to show each subscriber their link and count.

Lists a newsletter's referrals, newest first, 50 a page: who referred whom, and whether it counted. A referral is pending until the new subscriber confirms, credited once it counts, and rejected when it never will: a self-referral, a repeat of one inbox or network, a flood, an address that can't be emailed. Pass nextCursor back as cursor for the next page.

Lists the subscribers with the most confirmed referrals, most first, with how many each brought in.

Lists the tags a newsletter's contacts have had, each with how many contacts have it now. Filter list_contacts or a segment by a tag.

Gives a contact a tag, which segments can filter by and automations can start from (the tag added trigger). A contact has up to 30 tags and a newsletter up to 200. Adding a tag the contact has changes nothing.

Takes a tag off a contact. The tag stays on the newsletter's list of tags (delete_tag removes it everywhere).

Takes a tag off every contact of the newsletter and forgets it. It can't be undone. Segments and automations that name the tag keep working but match nobody.

Lists a newsletter's custom fields: values like a first name, a plan or a renewal date that each contact can have. Merge tags ({{first_name|there}}), segments and automations use them.

Adds a custom field to a newsletter, up to 20. Its type is text (500 characters), number or date (YYYY-MM-DD) and can't change later. Merge tags in campaigns name it by key: {{first_name}}, or {{first_name|there}} to print "there" for contacts without a value.

Changes a custom field's label, or whether the newsletter's signup form asks for it. Its key and type stay, since merge tags, segments and contacts' values use them.

Deletes a custom field and every contact's value for it. It can't be undone. Merge tags that name it print their fallback, and segments that use it match nobody.

Sets one custom field of a contact, or clears it with a null value. The value has to fit the field's type: text, a number, or a date as YYYY-MM-DD.

Lists a newsletter's saved segments, each with its rules and live counts: how many contacts it matches now and how many of those are active. A segment is a saved audience: send a campaign to it (update_campaign's segment) or start an automation from it.

Gets a segment with its rules, live counts and the newest contacts it matches.

Counts the contacts some rules match, live, without saving them: send either rules or the ID or name of a saved segment. matching is every status, active the contacts that can get email, sendable those the account never suppressed. The list cleanup and the account's warm-up still apply when a campaign goes out (preview_campaign_recipients).

Saves rules as a segment, up to 50 a newsletter. Rules combine conditions with all (and) or any (or), and a condition can be a group with its own all or any, one level deep. Conditions: status, tag (has or has_not), field (a custom field compared with eq, neq, gt, gte, lt, lte, contains, starts_with, is_set, is_not_set), signup_date (from, to), source, engagement (opened, clicked, opened_or_clicked or dormant over days, or never_opened) and imported. Text comparisons are case sensitive. It follows the list: contacts are matched each time it's counted or sent to.

Changes a segment's name, description or rules. Campaigns not yet sent and automations that use it follow the change; a campaign already sending keeps the audience it started with.

Deletes a saved segment. It can't be undone. A segment that a draft, scheduled or sending campaign, or an automation, still uses answers conflict: pick another audience for them first. Campaigns already sent keep the audience they went to.

Lists a newsletter's automations, newest first, each with its trigger, steps and how many contacts are in it, finished it or left it. An automation sends a series of emails and changes tags for each contact it starts for.

Gets an automation with its trigger, its steps (emails with their content) and how many contacts are in it.

Creates an automation as a draft: nothing is sent until activate_automation. A trigger starts it for a contact (they subscribe, get a tag, join a segment, or reach a date), and steps run in order: send an email, wait, add or remove a tag, or end. Up to 20 steps and 50 automations a newsletter. A contact enters an automation once. Emails go through the same checks as a campaign's: the account's plan emails, suppression and sending limits, with an unsubscribe link in each.

Changes an automation's name, trigger or steps. The trigger and steps of an active automation can't change: pause_automation first, then activate_automation again. Send all the steps, with the IDs you got back for the ones that stay, so contacts waiting on a step remain on it; a step without an ID is new.

Switches an automation on: from now on, contacts the trigger starts for get its emails without anyone asking again, until pause_automation. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. The account's plan, from address, postal address and every email's size are checked first, and again as the emails go out. A segment trigger starts only the contacts who join the segment from now on, unless includeExisting is true. Contacts who unsubscribe, bounce or complain leave it.

Stops an active automation: no new contacts enter and none move on, and no emails go out. Contacts in it continue where they were when it's activated again.

Deletes an automation: it leaves every list and the contacts in it are taken out, so nothing more is sent. It can't be undone. Emails already sent stay sent.

How an automation is doing: how many contacts entered, are in it, finished it or left it (and why), and for each step how many contacts wait to run it and, for emails, how many were sent, delivered, opened, clicked, bounced and complained.

Lists the account's own sending domains with their DNS records and status as last checked, and each newsletter's shared address (hello@<slug>.<shared domain>), which works with no setup.

Adds a domain to send from, in the account's own tenant at the email provider: emails are signed with DKIM and bounces return to a subdomain of it (rp.<domain> on PostShiba, bounce.<domain> on Amazon SES). The answer lists the DNS records to add; check_domain reads them once they're in. Newsletters can send from it once it's verified.

Asks the email provider and DNS again whether the domain's records are in, and looks up its DMARC record or its parent domain's. On PostShiba, a check within a minute of the last one answers what that one found. When its setup lists an archive step, the newsletter sending from the domain moves its archive and links to that subdomain once it points at FlockStack.

Removes a domain from the email provider, and its archive subdomain from FlockStack when its setup lists one. Newsletters on it can't send until they move to another address. Refused while a campaign from it is sending, paused or scheduled. Adding it again needs new DNS records.

Whether the account can take payments for products and paid subscriptions: on FlockStack Cloud, whether its connected Stripe account can take charges; on a self-hosted server, whether Stripe is set up. refresh asks Stripe for the account's latest status. FlockStack takes no cut of what you earn: your readers pay your own Stripe account, and only Stripe's own processing fee comes off.

Returns Stripe's own page where the account owner connects their Stripe account, or finishes connecting it: the account is created in their name, so they keep their money, refunds and disputes in their own Stripe dashboard. Nothing is connected until they finish there; get_payments_status shows when it is. Give the URL to the user. A self-hosted server answers conflict: it charges with its owner's own Stripe key. FlockStack takes no cut of what you earn: your readers pay your own Stripe account, and only Stripe's own processing fee comes off.

Gets the paid tier of a newsletter: whether readers can subscribe, its prices, its free trial and how many paid subscribers it has.

Turns a newsletter's paid tier on or off and sets its prices. With it on, readers subscribe monthly or yearly on the newsletter's /subscribe page through Stripe Checkout, pay your own Stripe account, and become paid contacts: campaigns can then go to paid readers only (audience paid), with a teaser on the web and the full issue by email, and paid readers get a manage-subscription link in every email. Send only the fields to change. Prices apply to new subscribers; people already subscribed keep what they pay. Turning it off closes the page to new subscribers but doesn't cancel anyone: end subscriptions in Stripe. FlockStack takes no cut of what you earn: your readers pay your own Stripe account, and only Stripe's own processing fee comes off.

Creates a digital product for one of the newsletter's readers to buy, as a draft: upload its file with set_product_file, then publish it with update_product (status active). It then has a page at /shop/<slug> on the newsletter's site, and buyers pay through Stripe Checkout and get a download link by email. FlockStack takes no cut: the buyer pays your Stripe account, and only Stripe's own processing fee comes off.

Changes a product's title, description, price, currency, slug or cover image, or puts it on sale (status active) or takes it back to a draft. Send only the fields to change. A price change applies to the next sale; earlier orders keep what they paid. Putting a product on sale needs its file and a Stripe account that can take payments (get_payments_status). FlockStack takes no cut: the buyer pays your Stripe account, and only Stripe's own processing fee comes off.

Lists the account's digital products, newest first, with how many each sold and what it earned.

Gets one product with its file, its public page and what it sold.

Takes a product off sale and off the shop. Its earlier buyers keep their download links, and its orders stay. update_product with status draft brings it back.

Stores the file buyers download, up to 15 MB, sent as base64. It is kept in a private bucket and only ever served through a signed link that expires, never from a public URL. Replacing it changes what every buyer downloads from then on.

Lists the orders of the account's products, newest first, 50 a page: who bought, what they paid, whether the download email went out, and refunds. Pass nextCursor back as cursor for the next page.

Gets one order: the buyer, the amount, refunds, how many times the file was downloaded and whether the download email went out.

Emails the buyer a new download link, valid for 7 days. The earlier link stops working. Refunded and disputed orders can't be resent. Refunds are made in your Stripe dashboard.

Lists the images uploaded to the account, newest first, 50 a page, so a campaign can use one again without uploading it twice. Pass nextCursor back as cursor for the next page.

Stores a PNG, JPEG, GIF or WebP image under 4 MB on FlockStack's CDN and returns its URL for campaign content. Send the file as base64 (under about 3 MB, since requests stop at 4.5 MB) or an https:// link FlockStack downloads. The URL never changes: sent emails keep pointing at it. list_images finds images uploaded before.

Lists the account's API keys, revoked ones included, with their level and when they were last used. Keys themselves are never shown again.

Creates an API key and returns it once; only its hash is stored. full can do everything a full key can, including creating more keys; signups can only add contacts, for keys that end up in website code. An account has up to 20 active keys: one more answers conflict until one is revoked.

Revokes an API key for good: requests with it answer unauthorized from now on. A key can revoke itself.

Lists the apps connected to the account with OAuth, such as ChatGPT, Claude and Grok Bot, with when they were connected and last used. Each one has full access, like a full access API key.

Disconnects an app connected with OAuth: its tokens stop working at once, and it has to ask for access again to come back. An app can disconnect itself.

The account's plan, subscription status and this month's usage against the plan's limits, with every plan on sale for comparison. Works without an active plan. A self-hosted server has no billing and answers billing_off.

Returns a billing page where the account owner picks up the change: Checkout without a paid plan (on a free plan too: the paid plan takes over), the Customer Portal with one (Stripe confirms the exact change there; Polar's portal lists the plans). Nothing changes until they confirm there. Give the URL to the user. A self-hosted server has no billing and answers billing_off.

Returns a Customer Portal link (Stripe or Polar) for the account owner: payment method, invoices, plan changes and cancellation. A self-hosted server has no billing and answers billing_off.

Starts an export of everything the account has, as ZIP files: every newsletter's contacts as a CSV (status, source, signup dates, engagement, tags), the suppression list, every issue and draft as Markdown and HTML with frontmatter (title, date, newsletter, archive address, status), the pictures they use, and a manifest.json that lists it all with each newsletter's settings. It is built in the background, which can take minutes for a large account; the account owner gets the download links by email, and get_account_export answers with them once status is ready. The links work for 7 days. Leaving is never a paid feature: it works for blocked accounts, paused ones and accounts without a plan. While an export is being made, calling this again answers that export with started false.

Gets an account export by ID, or the latest one: its status and, once it is ready, the download links. Works for blocked accounts and accounts without a plan.