Email automations: a welcome series triggered by events
Build an automated welcome email series triggered by user events, branch on user engagement, and manage delivery without third-party email tools.
On this page 7 sections
An email automation welcome series sends a sequence of scheduled, responsive messages when a new user joins a list or triggers an onboarding event. Rather than firing disconnected messages from cron jobs, you define a multi-step sequence that listens for contact actions, waits between messages, checks whether previous emails were opened, and stops immediately if the customer converts.
With thelastapi, you configure and run these flows directly using your project’s app key or the vibiz CLI. Here is how to construct, deploy, and monitor an event-driven welcome series.
How an event-triggered welcome series works
A static welcome message confirms an account creation, as covered in how to send a welcome email from a Next.js app. A welcome series, by contrast, guides a subscriber through onboarding over several days or weeks.
In thelastapi, marketing automations are completely isolated from transactional mail. Transactional messages like password resets send from info@<slug>.vibiz.app or your root mailbox. Automations and newsletters go out from a dedicated subdomain, hello@news.<slug>.vibiz.app by default (or news.yourcompany.com). This ensures that onboarding experiments never impact critical operational mail.
Every automation consists of three core components:
- A trigger: Either
contact_added(joining a specific list) orevent(such as completing an in-app setup step). - Steps: Timed delays (
wait), outbound messages (email), branching logic (condition), and termination (exit). - An exit event: A conversion target (such as
upgraded) that immediately removes the user from the sequence.
Because SPF, DKIM, and DMARC records align automatically upon setup, your domain builds an isolated sending reputation right away. For background on these email standards, see DKIM, SPF and DMARC: email deliverability basics, done for you.
Step 1: Initialize marketing email and set your postal address
Before sending an automation, initialize marketing email for your project and add your physical address. Federal compliance rules (CAN-SPAM) require a valid postal address in the footer of every marketing message. The API will refuse to activate campaigns without one.
Run the following commands using the CLI:
vibiz email setup
vibiz email settings set \
--from-name "Acme Support" \
--reply-to "hello@acme.com" \
--postal-address "100 Main St, Suite 400, San Francisco, CA 94105, USA"The vibiz email setup command provisions news.<slug>.vibiz.app and verifies its DNS authentication records within minutes. You can also configure this over HTTP:
curl -X POST https://thelastapi.dev/v1/projects/prj_123/email/marketing/setup \
-H "Authorization: Bearer $VIBIZ_API_KEY"
curl -X PATCH https://thelastapi.dev/v1/projects/prj_123/email/marketing \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H 'content-type: application/json' \
-d '{
"from_name": "Acme Support",
"reply_to": "hello@acme.com",
"postal_address": "100 Main St, Suite 400, San Francisco, CA 94105, USA"
}'Full configuration details for sending identity and custom domains are documented in the Email docs.
Step 2: Define your automation flow in JSON
An automation structure dictates the progression of each subscriber. Save your sequence definition as welcome-series.json:
{
"name": "User Onboarding Series",
"trigger": {
"type": "contact_added",
"list_id": "Users"
},
"exit_event": "upgraded",
"steps": [
{
"id": "welcome_step",
"type": "email",
"subject": "Welcome to Acme, {{{FIRST_NAME|there}}}",
"body": "Hi {{{FIRST_NAME|there}}},\n\nThanks for signing up! Here are three quick ways to get started with your account.\n\n[[Open Your Dashboard]](https://acme.com/dashboard)"
},
{
"type": "wait",
"days": 2
},
{
"type": "condition",
"if": {
"email_step": "welcome_step",
"did": "opened"
},
"yes": [
{
"type": "email",
"subject": "Pro tips for your first project",
"body": "Since you checked out our getting started guide, here are advanced tips to help you build faster."
}
],
"no": [
{
"type": "email",
"subject": "Need help getting started?",
"body": "We noticed you haven't opened the setup guide yet. Reply to this email if you hit any roadblocks."
}
]
},
{
"type": "wait",
"days": 4
},
{
"type": "email",
"subject": "How is everything going?",
"body": "Let us know how your first week has been. You can reply directly to this message."
}
]
}Key mechanics inside this file:
- Personalization tags:
{{{FIRST_NAME|there}}}injects the recipient's first name, falling back to "there" if missing. - Branching conditions: The
conditionstep checks whetherwelcome_stepwasopened(with machine clicks filtered out). Based on engagement, users receive tailored follow-up messages. - Conversion exits: If the user triggers an
upgradedevent at any point during their run, the sequence stops immediately.
Step 3: Deploy and activate the automation
Upload your JSON definition to create the automation:
vibiz email automation create --file welcome-series.jsonThe output returns an automation id (such as aut_123). Next, activate it:
vibiz email automation activate aut_123If you are using an AI agent or a restricted key, activating an automation requires owner approval. The API returns a 403 owner_only error containing a console_url where the account owner can review the sequence and turn it on. Account owners can also grant agents permission to send autonomously by setting an allowance (vibiz email settings set --agent-limit 2000).
To edit email text in a running automation, update the template directly. However, if you need to alter triggers, wait durations, or branch logic, pause the automation first:
vibiz email automation pause aut_123Attempting to change structural steps on an active sequence returns a 409 conflict with the code pause_first.
Step 4: Add contacts and emit events from your application
Your backend enrolls contacts and fires events using @vibiz/app with your server-side VIBIZ_APP_KEY.
When a customer registers on your site, upsert their contact record and attach them to the trigger list:
import { vibiz } from '@vibiz/app';
// Run on user signup
export async function handleUserSignup(user: { id: string; email: string; name: string }) {
await vibiz.contacts.upsert({
email: user.email,
first_name: user.name,
lists: ['Users'],
properties: {
user_id: user.id,
plan: 'free',
signed_up_at: new Date().toISOString(),
},
consent: {
method: 'app_signup',
text: 'Send me product updates and tips',
},
});
}As users interact with your product, track behavioral events. When a user reaches an exit milestone, emit the matching event:
import { vibiz } from '@vibiz/app';
// Run when a customer purchases a paid subscription
export async function handlePlanUpgrade(email: string, planTier: string) {
await vibiz.contacts.track(email, 'upgraded', {
plan: planTier,
});
}Emitting upgraded causes the automation engine to evaluate exit_event. The contact is removed from the welcome flow and receives no further onboarding emails.
If you are calling the API from Python, Go, or a shell script, use HTTP directly:
# Add a contact
curl -X POST https://thelastapi.dev/v1/app/contacts \
-H "Authorization: Bearer $VIBIZ_APP_KEY" \
-H 'content-type: application/json' \
-d '{"email":"ana@example.com","first_name":"Ana","lists":["Users"]}'
# Track an event
curl -X POST https://thelastapi.dev/v1/app/contacts/events \
-H "Authorization: Bearer $VIBIZ_APP_KEY" \
-H 'content-type: application/json' \
-d '{"email":"ana@example.com","name":"upgraded","properties":{"plan":"pro"}}'Step 5: Deliverability safeguards and limits
The automation engine enforces strict sending rates and deliverability rules to protect your domain reputation.
| Metric | Rule or Limit | Behavior when exceeded |
|---|---|---|
| Email Cost | $0.001 per sent contact email | Deducted from account credits |
| Initial Daily Send Limit | 500 emails on Day 1 | Doubles each clean day up to 100,000 |
| Hard Bounce Guard | 2.5% bounce rate threshold | Automation pauses (status: paused) |
| Spam Complaint Guard | 0.08% complaint rate threshold | Automation pauses (status: paused) |
| Suspension Threshold | 5% bounces or 0.3% complaints over 30 days | Project marketing sending blocked |
If an automation encounters high bounce rates, sending pauses automatically, and the account owner receives an email notification. You can inspect enrollment health and check step progression at any time:
vibiz email automation runs aut_123Contacts who unsubscribe, bounce, or file a complaint are excluded from all future sequences automatically. Even if a deleted contact is added again later, their suppression status persists.
If you also need to send one-off transactional receipts or system alerts without list management, read send transactional email from your app without touching DNS.
To get started, set up marketing on your project with vibiz email setup, add your physical address in settings, and define your onboarding sequence in JSON.
Frequently asked questions
Can an automated welcome email pause my transactional messages if it bounces?
No. Marketing automations run on a separate sending domain (`news.<slug>.vibiz.app`) with an isolated reputation, so bounces in a welcome series cannot pause password resets or billing receipts.
How does the system handle bot clicks and privacy scanners in conditions?
Machine opens, link scanners, and security proxies are automatically filtered out before evaluating condition steps, ensuring users are only branched based on real human interactions.
What happens if a user upgrades before the welcome series finishes?
If an automation has an `exit_event` configured (such as `upgraded`), tracking that event immediately removes the contact from the sequence and halts any pending emails.
How much does running an email automation welcome series cost?
Each sent email costs $0.001 (one-tenth of a cent), deducted from your account balance