Skip to content

Inbox Linking

Overview

Inbox linking connects a user's Gmail account to Unspend so that invoices can be automatically extracted from their email. The connection uses OAuth to securely grant read-only access to the inbox without exposing the user's password.

Currently only Gmail is supported.

User Journey

There are two ways to link an inbox:

  1. User navigates to the Inboxes page
  2. Clicks "Link inbox"
  3. A shareable link is generated — the user can copy it or open it directly
  4. The link opens a Google consent screen asking the user to authorize read-only Gmail access
  5. After authorization, the user is redirected back to Unspend
  6. The inbox appears on the Inboxes page with an "Active" status

Email Invites

  1. User navigates to the Inboxes page
  2. Clicks "Link inbox"
  3. Enters one or more email addresses in the "Send invites" section
  4. Each recipient receives an email containing a personalized linking URL
  5. The inbox appears immediately on the Inboxes page with a "Pending" status
  6. When the recipient clicks the link and completes authorization, the status changes to "Active"

Inbox States

Status Meaning
Pending Created via invite, waiting for the recipient to authorize
Active Authorization complete, ready for email processing
Authorisation Removed User revoked access from their Google account (not currently set programmatically — reserved for future detection)
Unlinked User explicitly unlinked the inbox from Unspend

Unlinking

Users can unlink an inbox at any time from the Inboxes page. This revokes the OAuth authorization with Google and marks the inbox as "Unlinked". If the revocation call to Google fails, the inbox is still unlinked on Unspend's side.

Post-Authorization

After completing OAuth, the system checks whether an Unspend account exists for the authorized email address. If one exists, the user is redirected to the Inboxes page. If not, a "link complete" confirmation page is shown.

Edge Cases

  • Duplicate email addresses: If an inbox is linked with the same email address that already exists for the organisation, the existing inbox is updated with the new credentials (keeping the same ID).
  • Invalid or expired links: The user sees an error message and can request a new link.
  • Re-authorization: If an inbox that was previously pending is authorized, its status transitions to Active and the refresh credentials are stored.