GuestOps/docs/mailboxes.md

Google mailbox management

Owners manage Google connections in Settings → Google mailbox. Staff can see synchronization health but cannot disconnect, reconnect or restart imports. The panel refreshes every 30 seconds while visible and offers a manual status refresh.

Connection and recovery

• Connect Google mailbox starts OAuth consent. Initial import covers seven days of inbox messages, in pages of up to 25 messages per worker cycle.
• Reconnect Google requires the same email address as the selected connection. Reconnection retains the mailbox ID and imported history, clears the page token and resumes the existing import window. It does not create a second copy of imported messages.
• Restart import pass clears the current page checkpoint without advancing the window. Use it for an import that needs another pass. It cannot bypass an active retry delay or repair revoked consent; those require waiting or reconnection respectively.
• Disconnect from GuestOps clears the stored encrypted refresh token, removes sending capability and stops new work once workers recheck the connection. Imported messages and drafts remain. Requests already in progress may finish.

Disconnect is local to GuestOps. To revoke Google's authorization as well, use the Google account connections link shown after disconnection and remove GuestOps access. This is deliberately separate: revoking a shared Google app grant can affect other sessions. GuestOps does not claim that a local disconnect revokes provider consent. Google's OAuth documentation describes revocation and account settings.

An OAuth flow started before the most recent connection change cannot reactivate that old connection. Concurrent connection changes use version checks. A mailbox email stays assigned to its hotel even after disconnect; moving it to another hotel requires a separately reviewed administrator migration.

Health states

The panel shows the last successful import page, last attempt, next scheduled attempt, whether additional pages remain, and a safe explanation. It never returns refresh tokens, provider page tokens or raw provider error bodies.

• Reconnect needed: revoked/expired refresh access, rejected access authorization, or unreadable protected credentials. The import worker stops trying until reconnection.
• Waiting for retry: temporary network/provider failures and quota responses. Import retries use an increasing delay, starting at about one minute and capped at about one hour, with jitter. A provider Retry-After can extend this up to one day.
• Configuration or permission failure: directs the administrator to review the Google app configuration or authorization; subsequent checks are spaced about an hour apart.
• Catching up: another page remains in the current import window. The last successful time refers to a page, not proof that the entire inbox is current.

Google's Gmail error guidance informs the error classification. A message returning 404 after listing is skipped. If Google rejects a saved pagination request with 400, GuestOps clears its page token, waits one minute and restarts the same window. Other malformed data can still require operator investigation; this is not a full mailbox repair or quarantine system.

Reply behavior across connection changes

Each new delivery approval records the current mailbox connection identity. Disconnect/reconnect changes that identity. Earlier pending approvals fail before submission and need explicit staff review/retry; automatic FAQ replies can return to staff review. A final connection check also runs after token acquisition. Requests already submitted to Google cannot be recalled. An uncertain delivery remains held and is never blindly resent.

Existing mailbox documents without a Version field remain compatible. Their connection identity defaults to empty until the next connection change. Sync updates require matching credentials, version and connected state, preventing an older worker from overwriting a disconnect or explicit checkpoint restart.

Acceptance before a hotel pilot

Automated fixtures cover pagination, duplicate imports, deleted messages, invalid grants, throttling, client configuration failures, reconnect account matching, missing read scope, cross-hotel ownership, stale workers, interrupted connections and queued-reply protection. MongoDB and HTTP tests exercise persistence, legacy documents, owner-only controls and preview isolation. These tests do not contact Google.

With a dedicated test mailbox on the HTTPS sandbox, verify consent and callback configuration, initial import, disconnect, manual removal of Google access, reconnect, read-only and send scopes, retained drafts, and staff review of rejected approvals. Keep FAQ live sending and other external writes off until their separate acceptance procedures pass. Full Gmail thread aggregation, history-repair tooling and attachments remain future work.