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 check runs on the next 15-minute cycle.
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 15 minutes we check the mailbox for new messages.
- A classifier decides which messages look like invoices, receipts, or statements. 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 scanning pipeline as everything else you upload manually. They show up in
Documentswith the original subject line as context. - Each email is processed exactly once. A per-message deduplication key at the database level guarantees a message is never re-processed, no matter how many polling runs see it — so you never get duplicate documents from the same email.
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 decide what's invoice-shaped during each check and pull only those attachments. There is no "TaxItEasy copy" of your full mailbox anywhere. A visible Activity log on the Email integration page shows exactly which emails were processed or skipped.
- OAuth tokens are encrypted with your personal key. The token Google or Microsoft issues us is encrypted before it touches our database — storage refuses to save it unencrypted. When you click
Disconnect, the stored token is wiped immediately and revoked at the provider (with retries if the provider is briefly unreachable). Deleting your account also revokes connected tokens before your encryption keys are destroyed. See where is my data stored for the storage details. - Read-only scope, enforced server-side. Both integrations request only read-mail access — we can never send, modify, or delete your email. And it's not just the request: a server-side scope whitelist rejects any token that comes back with wider permissions than read-only, so a mis-granted consent can't silently widen our access.
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