Email OAuth2 credentials
Description
Pure function: fetches an OAuth2 access token via the client credentials grant and builds an email credentials object that authenticates with SASL XOAUTH2. This is what Microsoft 365 and Google Workspace require for IMAP. For Microsoft 365 use host outlook.office365.com, the tenant's https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token endpoint, and scope https://outlook.office365.com/.default; for Gmail use imap.gmail.com and scope https://mail.google.com/. Tokens are cached and reused until they expire.
When to use
Use this for Microsoft 365 and for Google Workspace mailboxes, where password login over IMAP is either disabled or being retired. It runs the OAuth2 client credentials grant, which is the only flow a headless pipeline can complete with no human present, then authenticates with SASL XOAUTH2.
Microsoft 365 setup. Register an application in Entra ID, give it the
IMAP.AccessAsApp application permission, and grant admin consent. That
permission alone reaches every mailbox in the tenant, so also scope it to
the specific mailbox with Exchange Online PowerShell
(New-ServicePrincipal plus Add-MailboxPermission). Then set Token URL to
https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token, Scope to
https://outlook.office365.com/.default, and Host to
outlook.office365.com.
Google Workspace setup. Create a service account with domain-wide
delegation, authorize the https://mail.google.com/ scope for its client
ID in the Admin console, and set Host to imap.gmail.com.
Tokens are cached in the worker and reused until they expire, so a pipeline running every minute does not issue a token request every minute. If your provider only supports a delegated (authorization-code) flow, use Email access token credentials instead and obtain the token yourself.
Pins
Input pins
| Pin | Type | Default | Notes |
|---|---|---|---|
| Host | string | — | IMAP hostname. `outlook.office365.com` for Microsoft 365, `imap.gmail.com` for Google. |
| Port | integer | — | IMAP port. `0` selects the encryption default (993 for `SSL_TLS`). |
| Username | string | — | The mailbox to open, as a full email address. With the client credentials grant this is the mailbox the application acts on, not the identity it signs in as — the application must have been granted access to it. |
| Token URL | string | — | OAuth2 token endpoint. Microsoft 365: `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`. |
| Client ID | string | — | Application (client) ID from the identity provider's app registration. |
| Client secret | string | — | Client secret for the app registration. Wire this from a secret variable rather than typing it into the node. |
| Scope | string | — | OAuth2 scope. Microsoft 365: `https://outlook.office365.com/.default`. Google: `https://mail.google.com/`. |
| Extra parameters | map(string, string) | — | Extra form parameters added to the token request, for providers that need something beyond the standard grant. Empty for Microsoft and Google. |
| Encryption | Email encryption | SSL_TLS | `SSL_TLS` for both Microsoft 365 and Gmail. |
Output pins
| Pin | Type | Notes |
|---|---|---|
| Credentials | Email credentials | Opaque credentials object, interchangeable with the other two credential nodes' output. Wire it into Find emails, Get email, Find email folders, or Create email folder. |
Example
Poll a shared Microsoft 365 support mailbox. Store the client secret in a
secret variable and wire Read variable into Client secret. Set Host to
outlook.office365.com, Username to [email protected], Token URL to the
tenant’s v2.0 token endpoint, Scope to
https://outlook.office365.com/.default, and leave Port at 0. Feed
Credentials into Find emails (Folder INBOX, State UNREAD, Limit 25),
then loop the results into Read email and Set email flag.