# 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.

**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](https://thelastapi.dev/blog/welcome-email-nextjs). 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:
1. **A trigger:** Either `contact_added` (joining a specific list) or `event` (such as completing an in-app setup step).
2. **Steps:** Timed delays (`wait`), outbound messages (`email`), branching logic (`condition`), and termination (`exit`).
3. **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](https://thelastapi.dev/blog/dkim-spf-dmarc-deliverability).

## 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:

```bash
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:

```bash
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](https://thelastapi.dev/docs/email).

## 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`:

```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 `condition` step checks whether `welcome_step` was `opened` (with machine clicks filtered out). Based on engagement, users receive tailored follow-up messages.
- **Conversion exits:** If the user triggers an `upgraded` event 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:

```bash
vibiz email automation create --file welcome-series.json
```

The output returns an automation id (such as `aut_123`). Next, activate it:

```bash
vibiz email automation activate aut_123
```

If 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:

```bash
vibiz email automation pause aut_123
```

Attempting 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:

```ts
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:

```ts
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:

```bash
# 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:

```bash
vibiz email automation runs aut_123
```

Contacts 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](https://thelastapi.dev/blog/send-transactional-email-no-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

---

Published 2026-11-15 · https://thelastapi.dev/blog/email-automation-welcome-series
