How can I connect an account using OAuth2?

OAuth2 lets LeadSwift send and read email on your behalf without ever storing your password. Instead of a password or app password, you authorise LeadSwift once and it uses a secure token.

Important for Microsoft 365 / Outlook users: Microsoft has already disabled password (Basic) authentication for IMAP in all tenants. If you want LeadSwift to read replies or use the Unibox with a Microsoft account, OAuth2 is the only option available today.

Sending (SMTP AUTH) still works with a password for now, but that is ending too: Microsoft will disable it by default for existing tenants at the end of December 2026 (administrators will still be able to switch it back on), and tenants created after that date will not have it available at all. A final removal date is due to be announced in the second half of 2027.

Google accounts can continue to use an App Password (see "How do I send emails using Gmail or Google Workspace?"), which is much simpler and has no expiry pitfalls. Use OAuth2 for Google only if your organisation has disabled App Passwords.

What you will need

Whichever provider you use, you will end up with a few values to paste into LeadSwift under Email settings:

  • Client ID — always required
  • Client Secret — always required
  • Refresh Token — for Google, and for Microsoft "delegated" setups
  • Tenant ID — for Microsoft "app-only" setups instead of a Refresh Token

You do not need to fill in the SMTP Username and Password when using OAuth2. Leave them blank.

Google / Google Workspace

1. Go to the Google Cloud Console and create a project if you do not already have one

2. Go to APIs & Services › Credentials, select Create Credentials › OAuth client ID, and choose Web application

3. Under Authorised redirect URIs, add:

https://developers.google.com/oauthplayground

4. Save, then copy your Client ID and Client Secret

5. Open the Google OAuth Playground. Click the gear icon (top right), tick "Use your own OAuth credentials", and paste in your Client ID and Client Secret

6. In the left-hand box, type this scope exactly and press Authorize APIs:

https://mail.google.com/

7. Sign in and approve access, then press Exchange authorization code for tokens

8. Copy the Refresh token (it begins with 1//)

9. In LeadSwift, enter the following on your sending account:

SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Encryption: TLS
IMAP server: imap.gmail.com
Client ID: [Your Client ID]
Client Secret: [Your Client Secret]
Refresh Token: [Your Refresh token]
Tenant ID: [leave blank]
SMTP Username / Password: [leave blank]

Important — avoid the seven day expiry: If your OAuth consent screen is left on a publishing status of Testing, Google issues refresh tokens that stop working after seven days. Your account will connect fine and then mysteriously stop days later.

To avoid this, open APIs & Services › OAuth consent screen and either:

  • Set the User type to Internal — available if you use Google Workspace, and the simplest option. No verification is required and tokens do not expire on a timer.
  • Or set the publishing status to Production. Because https://mail.google.com/ is a restricted scope, an External app in Production shows an "unverified app" warning and is subject to Google's verification requirements for wider use.

If neither suits you, an App Password is the easier path for Google.

Microsoft 365 / Outlook

Microsoft offers two ways to do this. Pick one.

  • App-only (recommended for organisations) — an administrator sets it up once and it covers every mailbox in the tenant. No refresh tokens to manage. Requires admin access and a few PowerShell commands.
  • Delegated — each mailbox is authorised individually and produces its own Refresh Token. No PowerShell needed, but must be repeated per mailbox.

Microsoft option A: App-only (no Refresh Token)

1. In the Azure Portal, go to App registrations and select New registration. Give it a name and register it

2. From the Overview page, copy the Application (client) ID and the Directory (tenant) ID

3. Go to Certificates & secrets, create a New client secret, and copy its Value immediately (it is only shown once)

4. Go to API permissions › Add a permission › APIs my organization uses, search for Office 365 Exchange Online, and choose Application permissions. Add:

IMAP.AccessAsApp
SMTP.SendAsApp

5. Select Grant admin consent for your tenant

6. In Exchange Online PowerShell, register the application and grant it access to each mailbox you will send from:

Install-Module -Name ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <tenantId>

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID>

Add-MailboxPermission -Identity "[email protected]" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

Important: The OBJECT_ID must be taken from the Enterprise applications page in Azure, not from App registrations. Using the wrong one is the most common cause of authentication failing later, and the error message will not make this obvious.

7. In LeadSwift, enter the following on your sending account:

SMTP Host: smtp.office365.com
SMTP Port: 587
SMTP Encryption: TLS
IMAP server: outlook.office365.com
Client ID: [Application (client) ID]
Client Secret: [Client secret value]
Refresh Token: [leave blank]
Tenant ID: [Directory (tenant) ID]
SMTP Username / Password: [leave blank]

Important: The Tenant ID must be your actual Directory (tenant) ID. The word common is not accepted here — it is only valid for interactive sign-in, not for app-only access.

Microsoft option B: Delegated (with a Refresh Token)

1. Register an application in the Azure Portal as above, and add a redirect URI you can use to complete sign-in

2. Under API permissions, choose Delegated permissions for Office 365 Exchange Online and add:

https://outlook.office.com/SMTP.Send
https://outlook.office.com/IMAP.AccessAsUser.All
offline_access

3. Complete the sign-in flow for the mailbox you want to connect, and copy the Refresh Token that is returned

4. Enter the same values as Option A, but put your Refresh Token in and leave Tenant ID blank

Important: The offline_access permission is what makes Microsoft return a Refresh Token. Without it you will only get a short-lived token and the connection will stop working within an hour.

Common problems

  • "OAuth2 is only partly filled in" — you need Client ID and Client Secret, plus either a Refresh Token or a Tenant ID. Filling in both is not required.
  • Token exchange fails — the Client ID and Secret must belong to the same application that issued your Refresh Token. If you regenerated the secret, the old one stops working.
  • Token works but IMAP fails (Microsoft app-only) — the Azure side is correct but Exchange has not been told to allow it. Re-check the New-ServicePrincipal and Add-MailboxPermission steps, and confirm you used the Object ID from Enterprise applications.
  • IMAP fails with a Microsoft account and no OAuth set up — this is expected. Microsoft has already disabled password authentication for IMAP in all tenants, so a username and password can no longer connect. OAuth2 is required.
  • IMAP is switched off for the mailbox — OAuth cannot override this. An administrator may need to enable IMAP access for the mailbox before any connection will succeed.
  • Worked, then stopped after about a week (Google) — your OAuth consent screen is still on Testing status, which expires refresh tokens after seven days. Switch the User type to Internal, or the publishing status to Production, then generate a new Refresh Token.
  • Client secret expired — Azure client secrets have an expiry date. Create a new one and update it in LeadSwift.