When a user opens the app for the first time, present an onboarding flow that
invites them to add their email accounts, then drops them into their inbox. This
replaces today's empty experience — a blank inbox with an "Add account" button
(MailboxScreen.NoAccountState).
Product spec
When a user opens the app for the first time, the app should present an onboarding
flow inviting the user to add their email accounts.
Vendors supported:
Outlook/Hotmail
Gmail
Yahoo
iCloud
Other IMAP/SMTP
When an account is added during the onboarding flow, ask the user if they want to
add more accounts. If they tap yes, push them back to the account/vendor picker.
If no, continue to the first account they added and its inbox.
Auth per vendor:
Outlook/Hotmail — OAuth 2.0 through Microsoft (already implemented).
Gmail, Yahoo, iCloud — preconfigured IMAP/SMTP with an app password, biased
toward STARTTLS where supported; link the user to the vendor's app-password page and
explain what an app password is and that it must be stored carefully and securely, as
it grants access to their account.
Other IMAP/SMTP — the existing manual setup form.
Decision log
Gmail uses an app password (preconfigured IMAP/SMTP), not OAuth, per the spec
above. This diverges from the README ("no stored passwords for Gmail") and leaves the
existing GmailAuthManager / AuthType.OAUTH_GMAIL OAuth path unused for onboarding —
the README is reconciled in #31. Note this requires the user to have 2-Step Verification
enabled on their Google account before Google will mint an app password.
Fresh install with no accounts opens the onboarding welcome, not a blank inbox.
The vendor picker offers Outlook/Hotmail, Gmail, Yahoo, iCloud, and Other IMAP/SMTP,
each routing to the correct setup path.
App-password vendors show preconfigured servers, explain app passwords, and link to
the vendor's app-password page.
After each successful add, the user is asked whether to add another; yes returns to
the picker, no opens the first added account's inbox.
"Add account" from Settings / the mailbox reuses the same picker + setup screens (no
duplicate UI).
## Summary
When a user opens the app for the first time, present an onboarding flow that
invites them to add their email accounts, then drops them into their inbox. This
replaces today's empty experience — a blank inbox with an "Add account" button
(`MailboxScreen.NoAccountState`).
## Product spec
When a user opens the app for the first time, the app should present an onboarding
flow inviting the user to add their email accounts.
Vendors supported:
- Outlook/Hotmail
- Gmail
- Yahoo
- iCloud
- Other IMAP/SMTP
When an account is added during the onboarding flow, ask the user if they want to
add more accounts. If they tap **yes**, push them back to the account/vendor picker.
If **no**, continue to the first account they added and its inbox.
Auth per vendor:
- **Outlook/Hotmail** — OAuth 2.0 through Microsoft (already implemented).
- **Gmail, Yahoo, iCloud** — preconfigured IMAP/SMTP with an **app password**, biased
toward STARTTLS where supported; link the user to the vendor's app-password page and
explain what an app password is and that it must be stored carefully and securely, as
it grants access to their account.
- **Other IMAP/SMTP** — the existing manual setup form.
## Decision log
- **Gmail uses an app password (preconfigured IMAP/SMTP), not OAuth**, per the spec
above. This diverges from the README ("no stored passwords for Gmail") and leaves the
existing `GmailAuthManager` / `AuthType.OAUTH_GMAIL` OAuth path unused for onboarding —
the README is reconciled in #31. Note this requires the user to have 2-Step Verification
enabled on their Google account before Google will mint an app password.
## Breakdown
- [ ] #26 — first-run navigation scaffold + welcome
- [ ] #27 — account vendor picker
- [ ] #28 — preconfigured provider registry (Gmail/Yahoo/iCloud)
- [ ] #29 — app-password guided setup screen
- [ ] #30 — "add another account?" prompt + first-account landing
- [ ] #31 — onboarding E2E test + docs/strings
Suggested order: **#26 → #28 → (#27, #29) → #30 → #31**.
## Acceptance criteria (whole epic)
- Fresh install with no accounts opens the onboarding welcome, not a blank inbox.
- The vendor picker offers Outlook/Hotmail, Gmail, Yahoo, iCloud, and Other IMAP/SMTP,
each routing to the correct setup path.
- App-password vendors show preconfigured servers, explain app passwords, and link to
the vendor's app-password page.
- After each successful add, the user is asked whether to add another; **yes** returns to
the picker, **no** opens the first added account's inbox.
- "Add account" from Settings / the mailbox reuses the same picker + setup screens (no
duplicate UI).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Summary
When a user opens the app for the first time, present an onboarding flow that
invites them to add their email accounts, then drops them into their inbox. This
replaces today's empty experience — a blank inbox with an "Add account" button
(
MailboxScreen.NoAccountState).Product spec
When a user opens the app for the first time, the app should present an onboarding
flow inviting the user to add their email accounts.
Vendors supported:
When an account is added during the onboarding flow, ask the user if they want to
add more accounts. If they tap yes, push them back to the account/vendor picker.
If no, continue to the first account they added and its inbox.
Auth per vendor:
toward STARTTLS where supported; link the user to the vendor's app-password page and
explain what an app password is and that it must be stored carefully and securely, as
it grants access to their account.
Decision log
above. This diverges from the README ("no stored passwords for Gmail") and leaves the
existing
GmailAuthManager/AuthType.OAUTH_GMAILOAuth path unused for onboarding —the README is reconciled in #31. Note this requires the user to have 2-Step Verification
enabled on their Google account before Google will mint an app password.
Breakdown
Suggested order: #26 → #28 → (#27, #29) → #30 → #31.
Acceptance criteria (whole epic)
each routing to the correct setup path.
the vendor's app-password page.
the picker, no opens the first added account's inbox.
duplicate UI).