Onboarding Emails

Automated drip campaign that guides new users through database connection, first query, and team setup.

Onboarding emails are an automated drip campaign sent to new users after signup. Each email is triggered by a milestone (e.g., connecting a database, running a first query) or sent on a time-based fallback if the milestone is not reached.

SaaS

Onboarding emails are pre-enabled on app.useatlas.dev — new users receive the welcome sequence automatically. No configuration needed.

Self-hosted prerequisites

Internal database configured (DATABASE_URL)
Email delivery configured (RESEND_API_KEY or ATLAS_SMTP_URL)
Feature flag enabled (ATLAS_ONBOARDING_EMAILS_ENABLED=true)

Email Sequence

The onboarding sequence consists of five milestone-driven emails:

Step	Trigger Milestone	Fallback	Description
`welcome`	`signup_completed`	Immediate	Welcome email with getting-started links
`connect_database`	`database_connected`	24h after signup	Prompts the user to connect their first datasource
`first_query`	`first_query_executed`	72h after signup	Encourages the user to ask their first question
`invite_team`	`team_member_invited`	7 days after signup	Suggests inviting colleagues
`explore_features`	`feature_explored`	7 days after signup	Highlights advanced features (notebook, scheduled tasks, actions)

Each email is sent at most once per user. If the user completes the milestone before the fallback timer fires, the email is sent immediately on milestone completion.

Configuration (Self-Hosted)

SaaS

On app.useatlas.dev, onboarding emails are enabled by default with no additional setup. Skip this section.

Self-hosted setup

Enable onboarding emails via environment variable:

ATLAS_ONBOARDING_EMAILS_ENABLED=true
RESEND_API_KEY=re_...            # or ATLAS_SMTP_URL for HTTP webhook-based delivery (POST JSON)
ATLAS_EMAIL_FROM=Atlas <noreply@yourdomain.com>  # optional, defaults to "Atlas <noreply@useatlas.dev>"

See Environment Variables for all email configuration options.

Admin Management

Admins can view onboarding email status for their organization via the admin API:

List statuses — GET /api/v1/admin/onboarding-emails returns per-user progress (sent steps, pending steps, unsubscribe status)
View sequence — GET /api/v1/admin/onboarding-emails/sequence returns the configured sequence steps with triggers and timing

See the API Reference for full endpoint documentation.

Unsubscribe & Resubscribe

Every onboarding email includes an unsubscribe link. Users can:

Unsubscribe — click the link in any onboarding email (GET /api/v1/onboarding-emails/unsubscribe?userId=...)
Resubscribe — POST /api/v1/onboarding-emails/resubscribe with { userId } in the body

Unsubscribed users will not receive any further onboarding emails. Resubscribing resumes the sequence from the next unsent step.