Send automatic emails to your customers

An email flow is an email that we send for you when something happens to a customer: an order that nobody paid, a server that did not finish setting up, a free account that could use a paid plan, a service that ended, a new sign-up, or a customer who has been with you for a month. There are six flows. Each is off until you turn it on, and each sends only to customers who qualify when it runs.

Two flows are service emails about the customer's own order, and they need no marketing consent. The other four are marketing emails, and they go only to customers who agreed to marketing email. Every flow stops at the unsubscribe list.

• You need the Owner or Admin role in the organization. Your team can use the same settings in the staff console, under Marketing.
• The emails go out through your organization's mail settings, the same as your other customer emails. They use your brand's name and layout, and the links point at your storefront.
• Marketing flows send only to customers who agreed. Customers agree when they sign up, in their account settings or on the newsletter form. Collect newsletter sign-ups and manage unsubscribes describes how.

Each flow is a key in the API. Its settings are the numbers you can change; a flow with no setting has none.

Key unpaid_invoice. Service email, two steps.

Who gets it

A customer who has never paid an invoice for more than 0 and whose first order is waiting for payment: its invoice is unpaid or overdue, nothing on it is paid, its service is still pending, and the invoice is at most 7 days old.

When

Step 1 goes out delay_hours after the invoice was made. Step 2 goes out 72 hours after it (delay_hours plus 24 hours when the delay is 48 hours or more, so the two emails are never at the same time).

What stops it

The invoice is paid or cancelled, or the order is no longer waiting for payment. A step that is waiting when that happens is cancelled and never sent.

Settings

delay_hours, a whole number from 1 to 72 (default 24).

This flow comes in addition to the invoice email your customer already gets when the invoice is made.

Key stuck_setup. Service email, one step.

Who gets it

A customer whose service is in pending, provisioning or failed and has been for delay_hours. The service must be paid for or never have needed payment. We count the hours from the payment, or from when the order was made if that is later than the payment.

When

Once for each service, when it has waited delay_hours.

What stops it

The service is running, or its state changed to something else, before the email goes out.

Settings

delay_hours, a whole number from 1 to 48 (default 2).

Key free_upgrade. Marketing email, one step.

Who gets it

A customer who agreed to marketing email, has only free servers, has at least one active free server and has had the account for after_days days. A customer who got one of the free server inactivity emails in the last 3 days waits.

When

Once for each customer, ever. When you turn the flow on, every customer who qualifies gets it, at most 500 customers in each ten-minute pass.

What stops it

The customer buys a paid service, or no longer has an active free server, before the email goes out.

Settings

after_days, a whole number from 3 to 60 (default 10).

Key winback. Marketing email, one step.

Who gets it

A customer who agreed to marketing email and whose last paid service ended (terminated or cancelled) after_days days ago, and not more than 3 days before that. The customer must have no service that is pending, active or suspended, and no unpaid or overdue invoice. We take the end time from the cancellation record of the service, or from its last change when there is none.

When

Once for each ended service, inside that 3 day window.

What stops it

The customer orders again or owes money before the email goes out.

Settings

after_days, a whole number from 3 to 90 (default 7). coupon_code, a coupon of your organization or nothing. The email shows the code, and its plans link carries it as ?coupon=, which your storefront reads. If the coupon is paused, expired or deleted by the time the email goes out, the email goes out without it.

Key onboarding. Marketing email, two steps.

Who gets it

A new customer who agreed to marketing email and has no service on a paid plan. A free server does not count as a paid service.

When

Step 1 one day after the customer signed up. Step 2 three days after.

What stops it

The customer gets a paid service. Step 2 does not need step 1 to have gone out.

Settings

None.

Key review_invite. Marketing email, one step.

Who gets it

A customer who agreed to marketing email, whose first paid invoice (more than 0 in total) was paid after_days days ago, and not more than 3 days before that, and who still has an active service.

When

Once for each customer.

What stops it

The customer has no active service when the email goes out, or the review link is no longer saved and on.

Settings

after_days, a whole number from 14 to 90 (default 30).

You can turn this flow on only when your Trustpilot review link is saved and on in the review settings. The answer to the request says 422 with the field enabled otherwise. The email asks for a review and offers nothing for it.

• A customer gets at most one flow email in 3 days, from any flow. The two steps of one flow's series do not count against each other. When two flows qualify the same customer, the one listed first above takes the slot, and the service flows go before the marketing flows.
• Only customers whose account is active get an email. A customer whose address cannot receive mail, such as one ending in .invalid, is left out.
• An address on the unsubscribe list gets no flow email, whatever the customer agreed to.
• Every email ends with an unsubscribe link: "stop these reminders" in the service flows. Using it puts the address on the unsubscribe list, which stops every flow and every marketing email to that address and cancels the flow emails that were waiting. It does not stop invoices, receipts or other emails about the customer's own services. The email also carries a one-click unsubscribe header for mail apps.
• Every ten minutes we work through each active organization that has a flow on. A pass looks at no more than 500 customers for each flow and sends no more than 200 emails for your organization, service emails first. The rest wait for the next pass.
• An email is checked again just before it goes out. When its reason has gone (the invoice was paid, the server is running, the customer stopped agreeing to marketing email, or you turned the flow off) it is cancelled. An email that is more than 24 hours late is skipped, because a reminder about an invoice that old would be stale.
• Turning a flow on does not mail anyone straight away: the next pass finds the customers who qualify at that time.

Each email is a template with the name below. If you saved a template of your own under that name, we send yours instead of ours.

A template can use customer_name, brand_name, unsubscribe_url and the links its flow has: payment_url, invoice_number, amount, currency, due_date and service_name for the unpaid invoice flow; service_url, service_name and support_url for stuck setup; plans_url for the free nudge; plans_url, coupon_code and service_name for the win-back; login_url, plans_url and support_url for onboarding; and review_url for the review invitation.

Owners and admins run the flows in the dashboard. Your team can do the same in the staff console, as Marketing audience in the staff console describes. A member with another role does not see the page, and its address opens Overview.

1. In the dashboard, open the organization, then Settings, then Email flows.
2. Find the flow's card. The six cards are in a fixed order: "Unpaid first invoice", "Stuck setup", "Free to paid nudge", "Win-back", "Onboarding" and "Review invitation". Each says whether it is a Service or a Marketing flow and shows On or Off, with what it does under its name.
3. Turn on Send this flow, and set the numbers the card asks for, such as "Hours before the first email". Each hint says what the number does and the range it takes. "Coupon code" on the win-back is optional and must be a coupon of your store.
4. Select Save changes. The page says "Win-back turned on." when the switch was the only change, and "Win-back saved." otherwise. Each card saves alone, so what you typed in another card stays unsaved until you save that card. A value the API refuses shows its sentence under the input, and focus moves there.
5. Under "Check it looks right", select Send a test to me. A flow with two emails also offers "Email 1" and "Email 2". The test goes to your own address, the subject starts with [Test], and the card says where it went. It is off while the card has unsaved changes, because the test uses the saved settings. You can send 10 tests an hour. The card shows the API's sentence when you pass that, when your address is on the unsubscribe list and when the mail server refuses the email.

When it works, the card's badge reads On and its counts move as the flow runs: Scheduled, Sent, Skipped, Canceled and Failed, with Last sent. A flow starts at its next pass, within ten minutes, and mails only customers who qualify from then on.

The review invitation cannot be turned on until a Trustpilot review link is saved and the review prompt is on. Its card says This flow cannot be turned on yet with the reason, and Open Reviews and announcements goes to the page where you set the link. If the link is removed later while the flow is on, the card says This flow cannot send yet.

Flow emails under the cards is the log. Choose "All flows" or one flow and "Any status" or one status, and the filters and the page stay in the address. Each row names the customer, the flow and its email, its status, when it is due and when it was sent. A Skipped or Failed email shows its reason under the status.

1. Read your flows with GET /flows. Each entry has enabled, config (the saved settings with defaults filled in), fields (the name, range and default of each setting) and blocked, the sentence that says why a flow cannot send even when it is on.
2. Turn the flow on and set its numbers with PUT /flows/{key}. Send only what changes.
3. Send yourself a test, as Send yourself a test says.
4. Wait for the next pass, at most ten minutes, then read the log.

curl -X PUT https://api.coritan.com/api/v1/orgs/acme/flows/winback \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "config": {"after_days": 7, "coupon_code": "COMEBACK"}}'

The answer is the flow as GET lists it (shortened here), and the names that changed:

{
  "flow": {
    "key": "winback", "label": "Win-back", "kind": "marketing", "enabled": true,
    "config": {"after_days": 7, "coupon_code": "COMEBACK"},
    "template_slugs": ["flow_winback"], "blocked": null,
    "stats": {"scheduled": 0, "sent": 0, "skipped": 0, "failed": 0, "canceled": 0, "last_sent_at": null}
  },
  "changed": ["enabled", "config.coupon_code"]
}

config keys replace the saved ones. Send "coupon_code": null to remove a coupon. Saving what is already saved changes nothing and writes no audit entry. A value that does not fit answers 422 with detail, the sentence to show, and field, the input it belongs to, and changes nothing:

{ "detail": "Days after the service ended must be a whole number from 3 to 90.", "field": "config.after_days" }

POST /flows/{key}/test sends the flow's email to the address on your own account, filled with made-up facts and your brand's links, and the subject starts with [Test]. It goes out whether or not the flow is on, as a service email, so it needs no marketing consent. It is not in the log.

Send {"step": "2"} to test the second email of a flow that has two. A step the flow does not have answers 422 with the field step. The answer is {sent, to, flow, step, template}.

• If your address is on your organization's unsubscribe list, nothing is sent and the answer is 409.
• If the mail server does not take the email, the answer is 502.
• You can send at most 10 tests an hour. The eleventh answers 429.

GET /flows/messages lists every email the flows scheduled, newest first. Filter it with flow and status. limit takes 1 to 200 (50 by default) and offset pages through; count is the total that match. Each row has flow, step, status, email, scheduled_at, sent_at, customer_id and error.

scheduled

Waiting for the next pass.

sent

Handed to the mail server.

skipped

Left out on purpose. error says why: the address is on the unsubscribe list, the account is not active, another flow email went to the customer in the last 3 days, or the email was more than 24 hours late.

canceled

Its reason went before it was sent: the invoice was paid or cancelled, the server is running, the customer has a paid service or an active service again, the customer stopped agreeing to marketing email, or the flow was turned off.

failed

The mail server did not take it. A failed email is not tried again.

GET /flows shows the same counts for each flow in stats, with the time of the last email it sent in last_sent_at.

After the next pass, GET /flows/messages lists a row for each customer who qualified, sent for the ones who got the email. The customer's email shows in Sent email under the template's name. The same flow never emails the same customer for the same order, service or sign-up twice.

A flow is on and nothing is sent

Read blocked in GET /flows: the review invitation sends nothing without a saved review link. Marketing flows need customers who agreed to marketing email. Then read the log for skipped and canceled rows, which say why.

A customer qualified and got nothing

Look for their address in the log. The 3 day rule, the unsubscribe list and an account that is not active each leave a skipped row with the reason. A customer who has not agreed to marketing email gets no row from a marketing flow.

The review invitation answers 422

Save your Trustpilot review link and turn on the review prompt first. The review invitation reads the same link.

The win-back goes out without its coupon

The coupon was paused, expired or deleted when the email went out. Check the coupon, then the next customer's email carries it again.

The test answers 409

Your address is on the unsubscribe list of this organization. Take it off the list, or use another member's account for the test.

The staff console's routes under /api/v1/orgs/{org_slug}/staff/marketing/flows answer the same, for the Admin and Owner roles, and platform staff have the same routes for any organization in the admin console. All of them need an access token, sent as Authorization: Bearer $CORITAN_TOKEN.

Every change is recorded in the audit log as flows.updated (the flow, the names that changed and its settings before and after) or flows.test_sent.

• Collect newsletter sign-ups and manage unsubscribes
• Read the email you sent your customers
• Read the organization audit log

• Read the unsubscribe list and see who agreed to marketing email.
• Check the emails your customers got after the first pass.
• Follow what your team and the API changed when a flow's settings look wrong.