How do I connect Gmail, Outlook, or IMAP?

When to use a direct connection

There are two ways to get invoice emails into TaxItEasy, and they solve different problems:

• Email forwarding is best when invoices arrive at a single, predictable address and you can either set up a forwarding rule once or are happy to forward manually. It works with any provider, needs no OAuth, and is described in set up email forwarding.
• Direct connection is what you want when invoices land in the same inbox you use for everything else and you don't want to maintain a rule that filters them out. We connect to your mailbox with read-only access and pick the invoice-shaped emails ourselves.

Both can run on the same account at the same time. Most teams start with forwarding, then add a direct connection on top once they trust the matching.

The walk-through

The whole flow takes about a minute. There is one screen for Gmail and Outlook (the provider's own OAuth consent screen), or a short form for Generic IMAP. There is no multi-step setup wizard.

Step 1 — open the integration page

In the TaxItEasy app, go to Settings → Email integration. You'll see a list of any inboxes you've already connected, plus a Connect account button at the top right.

Step 2 — pick a provider

Click Connect account and choose one of:

• Gmail — for personal Gmail (@gmail.com) and Google Workspace addresses ([email protected] on Workspace).
• Outlook — for @outlook.com, @hotmail.com, @live.com, and Microsoft 365 business mailboxes.
• Generic IMAP — for anything else: Fastmail, Proton with bridge, Apple iCloud Mail, your own server, or a Workspace admin who has disabled third-party OAuth.

If you don't see your provider listed but it speaks IMAP, pick Generic IMAP.

Step 3a — Gmail or Outlook (OAuth, one screen)

You're redirected to Google or Microsoft, signed in if you aren't already, and shown a single consent screen. The scope we request is read-only mail access — literally the right to read message headers and message bodies and to download attachments. We cannot send, reply, delete, label, archive, or modify any email. The scope grant is printed in plain text on the consent screen; read it before you click Allow.

After you allow, you're redirected back to TaxItEasy. The connection appears as Active in the list, and the first poll runs within about a minute.

Step 3b — Generic IMAP (short form)

For Generic IMAP, you fill in four fields:

• IMAP host — for example, imap.fastmail.com.
• Port — usually 993 (SSL/TLS). We don't support cleartext IMAP on port 143.
• Email address — the address you're connecting.
• Password — almost always an app-specific password, not your normal account password. Most providers explain how to generate one inside their security settings ("App passwords", "Mail-specific password", or similar). If your provider doesn't offer app passwords, we recommend forwarding instead — see the troubleshooting section below.

When you click Test connection, we open a TLS session, log in, and read the most recent message header. If anything fails (wrong host, wrong port, password rejected, no TLS), the error from the IMAP server is shown verbatim so you can fix it.

Step 4 — what happens next

From the moment the connection is Active:

• Every 5 to 15 minutes (depending on plan and provider quotas) we fetch new message headers.
• A classifier decides which messages look like invoices, based on subject, sender, MIME structure, and attachment type. Newsletters, marketing, and personal email are skipped — see what happens when you forward a newsletter for the classification logic.
• Attachments from invoice-classified emails are pulled and run through the same OCR + extraction pipeline as everything else you upload manually. They show up in Documents with a small mail icon and the original subject line as context.

You can pause or disconnect any time from the same page — see how to disconnect an email account.

What we store, and what we don't

Direct connection looks more invasive than forwarding at first glance. It isn't, because of three design choices:

• We poll, we don't mirror. Your inbox is not copied to our servers. We hold message headers in memory for the duration of a poll, decide what's invoice-shaped, and pull only those attachments. Everything else is dropped before the next poll starts. There is no "TaxItEasy copy" of your full mailbox anywhere.
• OAuth tokens are encrypted with your account key. The refresh token Google or Microsoft issues us is encrypted before it touches our database. When you click Disconnect, the token is revoked at the provider (Google's /o/oauth2/revoke and Microsoft's equivalent) and the encrypted copy on our side is wiped in the same transaction. See where is my data stored for the storage details.
• Read-only scope, no exceptions. Both the Gmail and Outlook integrations request only the read-mail scope. We do not have a higher-scope mode available for users to opt in to. If a future feature ever needed write access, it would be a separate connection with a separate consent screen.

If you ever want to verify the connection's permissions out-of-band, both Google and Microsoft show every third-party connection at:

• Google: myaccount.google.com → Security → Third-party connections
• Microsoft: account.microsoft.com → Privacy → Apps and services

You can revoke us there in one click; we'll see the revocation on the next poll and mark the connection as Disconnected automatically.

Troubleshooting

My Workspace admin blocks third-party OAuth. Many Google Workspace and Microsoft 365 tenants restrict which third-party apps users can authorise. If you click Allow and land on an admin-approval page, your admin has to approve TaxItEasy as an allowed app, or you have to use forwarding instead. Most teams find forwarding simpler than fighting IT.

Generic IMAP rejects my password. This almost always means the provider expects an app-specific password rather than your real one. Search your provider's help center for "app password". If your provider doesn't offer them and only accepts your main password, treat that as a sign that the inbox should be reached via forwarding, not direct connection — sharing your primary password with any third party is not safe.

Gmail is connected but no documents show up. Open Settings → Email integration → Activity log on the same page. You'll see one row per poll, with how many emails were inspected and how many were classified as invoices. If inspected > 0 and invoices = 0, the classifier hasn't seen invoice signals. Forward one known invoice to your inbox address so the classifier sees a positive example, then check again on the next poll.

The connection went stale. OAuth tokens can be invalidated by the provider (password change, security event, periodic rotation). When that happens, the connection is marked Needs re-auth. Click it once, walk through the consent screen again, and you're done — no data loss; the next poll picks up where the last good one left off.

I want to switch from forwarding to direct. You don't have to choose. Add the direct connection, leave forwarding in place, and watch for a week. If direct is catching everything forwarding caught, delete the forwarding rule. If anything slips through, keep both.

Related

• Set up email forwarding — the no-OAuth alternative
• What happens when you forward a newsletter — how the invoice/non-invoice classifier decides
• How to disconnect an email account — clean removal + token revocation
• Where is my data stored? — Frankfurt residency + encryption at rest