Sign in and open your first mailbox

Use this guide when an operator already installed MailGen. For a new machine, start with first installation.

Before you start

Ask the operator for the Account HTTPS address and MailGen BFF HTTPS address. Ask which login method and mailbox provider your deployment supports. Your browser must trust the local HTTPS certificate. The certificate guide explains client trust.

A documentation URL opens these pages. It is not an application login or provider callback.

1. Sign in

Open the Account address with /login. Use the configured email/password account or an available Microsoft or Google button. Register only if your operator permits registration.

The first administrator uses the credentials configured during account setup. Other users must receive the required group membership and permissions.

After successful sign-in, open the BFF address. If sign-in returns to the wrong host or port, ask the operator to check the registered callback and public origins.

2. Select or connect a mailbox

Open /onboarding on the BFF HTTPS address. The page title is Connect Account. Without a selected account, it shows Connect your mailbox. With an account selected, it shows Prepare your mailbox.

Microsoft mailbox

Complete the prerequisites in Connect and provision one mailbox. Microsoft connection requires configured login credentials and an existing tenant connection with granted consent and usable app-only credentials. An empty database does not expose the Microsoft button from environment credentials alone.

1. If the intended Microsoft identity is not linked, select Continue with Microsoft.
2. Approve the identity-linking request and return to MailGen.
3. Check the selected account's email. In the workspace gate, Switch mailbox selects another account already connected to your login.
4. Select Start onboarding, or Set up mailbox in the workspace gate. Your actor needs mail.onboarding permission.
5. Read the displayed steps until Opening workspace… appears and the workspace opens.

The start action checks that you own the connected account. It does not require a pre-existing mailbox row or mailboxId. The worker resolves the Microsoft identity, creates or updates the local mailbox, and imports its data. An accepted start request does not mean import is complete.

For a setup failure, read the displayed run and step error. Use Retry onboarding, or Retry mailbox setup in the workspace gate, when offered. A successful identity link does not grant app-only Graph authority.

Personal Gmail mailbox

Complete Google Cloud setup. Your signed-in actor needs accounts.manage permission.

1. Under Connect your mailbox, select Continue with Google.
2. Approve the separate Gmail mailbox consent. Google application login alone does not grant this access.
3. Keep the same MailGen session through the callback. It returns to /onboarding and selects the connected Google account.
4. Wait at Prepare your mailbox. The page says Syncing your mailbox. MailGen opens when mail and search are ready.
5. Wait for Opening workspace… and the workspace to open.

Google initial synchronization starts automatically. It uses its own mailbox OAuth binding and progress, independently of Microsoft onboarding. If setup pauses, select Retry onboarding only when the page offers it. For denied access, check connector permissions with your administrator. For an encryption lock, restore the correct original personal key before retrying.

For an expired callback or session mismatch, return to /onboarding in the current session and restart the Google connection. Do not replay a saved callback URL.

3. Unlock content and read a message

Follow personal-key backup and unlock when the application requests an email key. A new owner creates the key and downloads its private-key backup. An owner with existing encrypted content imports the original backup. See encryption settings. A replacement key does not decrypt old data. An environment ZIP does not restore this personal key.

Wait for mailbox onboarding and synchronization. Open a folder, then a message. Check its body and, when present, a permitted attachment. A visible message row alone does not prove that its stored body is available.

4. Check a change

Use a disposable draft or another action your operator permits. Inspect the resulting state and, for Microsoft operations, the Sync Center. A queued or accepted action can still await provider confirmation. Read key concepts before interpreting these states.

If access fails

Symptom	Next action
Certificate error	Ask the operator for the public certificate and trust instructions. Never import a private key.
Login provider unavailable	Ask the operator to check connector configuration and the exact callback.
Empty mailbox list	Open /onboarding and check the available provider actions. Microsoft requires the tenant-connection prerequisite in Microsoft setup.
Locked message body	Follow personal-key backup and unlock for the correct owner's original key.
Accepted change does not appear at the provider	Inspect the operation state and provider-specific limits before retrying.

Continue with messages and conversations, search, or the application overview.