Skip to main content

Connect

Connect to a mail server

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

if ContinueOnError property is true, no error is caught when the project is executed even if Catch node is used.

Output​

  • Client Id - Id of the client that connects to the mail server.

Options​

  • Authentication Type - Specifies the method of authentication to connect to the mail server. Choose between Basic Authentication or OAuth2 Authentication.

    • Basic Authentication - Requires a username and password. The password typically isn't the email password; instead, you must generate an Application Password through your email service provider.
    • OAuth2 Authentication - You'll need to obtain the OAuth2 Client ID and Client Secret from your email service provider.

  • Mail Server Credentials - Credentials necessary to authenticate the connection to the mail server.

  • OAuth2 Token Credentials - This is required only when OAuth2 Authentication is chosen. A Document Category Type credential, containing {'client_id': '<your_client_id>', 'client_secret':'<your_client_secret>'}, should be created within a vault.

How It Works​

The Connect node establishes a connection to a mail server using either Basic Authentication (username/password) or OAuth2 Authentication. Here's the step-by-step process:

  1. Credential Validation - The node validates that proper credentials are provided from the vault
  2. Authentication Method Detection - Automatically detects whether to use Basic or OAuth2 based on credential type
  3. Connection Establishment - Connects to the mail server using IMAP protocol with TLS encryption
  4. Authentication - Authenticates using the selected method (Basic or OAuth2)
  5. Client ID Generation - Creates and returns a unique Client ID for subsequent mail operations
  6. OAuth2 Token Management - For OAuth2, handles token refresh and vault updates automatically

Requirements​

To use the Connect node, you need:

  • Mail Server Credentials stored in a vault (either EmailItem for Basic Auth or DocumentItem for OAuth2)
  • For Basic Auth: IMAP/POP3 server address, port, username, and application password
  • For OAuth2: Client ID, Client Secret, and mail server settings in JSON format
  • Network Access to the mail server (typically port 993 for IMAP with TLS)
  • OAuth2 Setup (if using OAuth2):
    • For Gmail: OAuth2 credentials from Google Cloud Console with https://mail.google.com/ scope
    • For Outlook/Office365: OAuth2 credentials from Azure AD with IMAP and SMTP scopes

Error Handling​

Error CodeDescriptionResolution
Core.Mail.Connect.ErrOnCreateConfiguration parsing failedCheck node configuration is valid JSON
Core.Mail.Connect.ErrCredentialsCredentials vault/item not selected or invalidSelect valid credentials from vault
Core.Mail.Connect.ErrDialTLSCannot connect to mail serverVerify server address, port, and network connectivity
Core.Mail.Connect.ErrLoginAuthentication failed (Basic)Verify username and password are correct
Core.Mail.Connect.ErrAuthenticationOAuth2 authentication failedCheck OAuth2 credentials and token validity
Core.Mail.Connect.ErrUnsupportedHostUnsupported OAuth2 providerUse Gmail or Outlook/Office365 for OAuth2
Core.Mail.Connect.ErrVaultCannot update vault with refreshed tokensCheck vault permissions
Core.Mail.ErrDialTLSTLS connection failedVerify SSL/TLS settings and certificates
Core.Mail.ErrLoginLogin credentials rejectedVerify credentials are correct and not expired

Usage Examples​

Example 1: Connect with Basic Authentication (Gmail)​

// Store credentials in vault as EmailItem
// IMAP Server: imap.gmail.com
// Port: 993
// Username: your-email@gmail.com
// Password: your-app-password (not regular password!)

// In flow: Use Connect node
// Set Authentication Type to "Basic Authentication"
// Select vault credentials
// Output: client_id (e.g., "mail_client_12345")

Example 2: Connect with OAuth2 (Gmail)​

// Create Document credential in vault with this JSON:
{
  "email": "your-email@gmail.com",
  "client_id": "your-google-client-id",
  "client_secret": "your-google-client-secret",
  "inbox.server": "imap.gmail.com",
  "inbox.port": 993,
  "smtp.server": "smtp.gmail.com",
  "smtp.port": 587
}

// In flow: Use Connect node
// Set Authentication Type to "OAuth2 Authentication"
// Select vault credentials
// First run will open browser for OAuth2 consent
// Subsequent runs use stored refresh token

Example 3: Connect to Outlook with OAuth2​

// Create Document credential in vault:
{
  "email": "your-email@outlook.com",
  "client_id": "your-azure-client-id",
  "client_secret": "your-azure-client-secret",
  "tenant_id": "common",
  "inbox.server": "outlook.office365.com",
  "inbox.port": 993,
  "smtp.server": "smtp.office365.com",
  "smtp.port": 587
}

// First run opens browser for Microsoft login
// Token is automatically refreshed and saved to vault

Usage Notes​

  • Application Passwords: For Basic Auth with Gmail/Outlook, you must use an app-specific password, not your regular account password
  • OAuth2 First Run: The first connection with OAuth2 opens a browser window for authentication. Subsequent connections use the stored refresh token
  • Token Refresh: OAuth2 tokens are automatically refreshed when expired and saved back to the vault
  • Connection Timeout: IMAP connections have a timeout to prevent hanging indefinitely
  • SMTP-Only Mode: You can create credentials with only SMTP settings (no IMAP) for send-only operations
  • TLS Security: All connections use TLS 1.0+ with SSL certificate validation (InsecureSkipVerify is set for compatibility)
  • Client Persistence: The Client ID remains valid throughout the flow execution and must be disconnected with the Disconnect node

Tips​

  • Use OAuth2 for Production: OAuth2 is more secure than Basic Auth and doesn't require storing passwords
  • Store Credentials Safely: Always use the vault to store credentials, never hardcode them in flows
  • Gmail App Passwords: Enable 2-factor authentication and create app-specific passwords at myaccount.google.com/apppasswords
  • Test Connection First: Use a simple Get Mail or List Folders node immediately after Connect to verify the connection works
  • Handle First OAuth2 Run: In headless environments, ensure the first OAuth2 authentication can open a browser
  • Connection Reuse: Store the Client ID in a variable and reuse it across multiple mail operations in the same flow
  • Proper Cleanup: Always use the Disconnect node at the end of your flow to close the connection properly