Send SMTP Email - Cognigy Documentation

Description

As of Cognigy.AI 2026.4.0, the OAuth2 authentication method for the Send SMTP Email Node is deprecated. The full removal of this authentication method is planned for Cognigy.AI 2026.16.0. To avoid disruptions in AI Agents using OAuth2 in this Node, migrate to the OAuth2 Client Credentials authentication method before the removal date.

Use the Send SMTP Email Node to send an email via an SMTP connection to a recipient.

Parameters

Email Service Configuration

Some email providers, such as Gmail, require you to configure your mail account to allow sending mail via SMTP before you can use it.

Authentication

You can use one of the following authentication methods:

• OAuth2 Client Credentials (recommended)

• OAuth2 (deprecated)

• Basic Auth

OAuth2 Client Credentials

OAuth2 Client Credentials is a token-based authentication method. It uses a client ID and client secret to obtain an access token and authenticate with the email provider. This authentication method provides a higher level of security than Basic Auth and doesn’t require refresh tokens.

To create a connection, follow these steps:

1. Next to the OAuth2 Client Credentials Parameters setting, click +.
2. Add a new connection or use an existing one:
   • Connection name — enter a unique connection name.
   • Token Endpoint URL — enter the email provider URL to retrieve the access token.
   • Client ID — enter the registered client ID of the application.
   • Client Secret — enter the registered client secret of the application.
   • (Optional) Scope — enter the scope of the access token, as defined in RFC 6749. Some email providers require the scope to be set. For example, use https://outlook.office365.com/.default if you’ve selected Office365 for the Email Service parameter. Refer to your email provider’s documentation to find the correct scope.
   • User — enter the email address from which the email is sent.
3. Click Create.

OAuth2

OAuth2 is a token-based authentication method. It uses access tokens generated by the service provider to grant authorization for client applications to access user data. Access tokens are unique identifiers that contain user, client application, and permission information. They are short-lived and can be revoked if necessary, providing a higher level of security than Basic Auth.

To create a connection, follow these steps:

1. Next to the OAuth2 Parameters setting, click +.
2. Add a new connection or use an existing one:
   • Connection name — enter a unique connection name.
   • user — add your email address.
   • clientId — add a registered client id of the application.
   • clientSecret — add a registered client secret of the application.
   • accessToken — add an access token. Required only if refreshToken is not available.
   • refreshToken — add a refresh token. If it is provided, the Node tries to generate a new access token if existing one expires or fails.
   • expiryDate — add an expiration Unix timestamp in milliseconds for the current accessToken.
   • accessUrl — add an HTTP endpoint for requesting new access tokens. This value defaults to Gmail https://accounts.google.com/o/oauth2/token.
   • tlsOption — specify one of the options if you want to connect with TLS:
     • tls — is used by default. TLS is a separate protocol that operates on a different port (usually port 443 for HTTPS).
     • starttls — is a command used to upgrade an existing insecure connection to a secure one within the same port.
     • none — don’t connect with TLS.
3. Click Create.

Basic Auth

Basic Auth is a simple authentication scheme where the client sends the user’s credentials (username and password) to the server in the HTTP header. It’s used for web applications requiring authentication and adds an Authorization header to the HTTP request. However, it has security limitations as the credentials are sent in clear text, and the server doesn’t provide a way to log out.

To create a connection, follow these steps:

1. Next to the Basic Auth Parameters setting, click +.
2. Add a new connection or use an existing one:
   • Connection name — enter a unique connection name.
   • username — add a login that you obtained from your email provider.
   • password — add a password that you obtained from your email provider.
3. Click Create.

Attachments

By default, the No Attachment option is selected.

Result Storage & Error Handling

Stop on Error

If switched on, the flow execution will halt in case the mail-sending fails.

Advanced

Example

This example shows how to configure OAuth2 Client Credentials with Microsoft 365 SMTP using Microsoft Entra ID.

Prerequisites

Before starting, ensure the following:

• Your Microsoft Entra account must have one of the following roles:
  • Application Developer (minimum).
  • Cloud Application Administrator or Global Administrator (recommended).
• The mailbox that will send emails must:
  • Be hosted in Microsoft 365 or Exchange Online.
  • Have SMTP AUTH activated.

Create a Multi-Tenant Application in Microsoft Entra ID

1. Log in to the Microsoft Entra admin center.
2. In the left sidebar, select Entra ID > App registrations.
3. Click New registration. On the Register an application page, enter a name, for example, Cognigy SMTP Integration.
4. In the Supported account types section, select Accounts in any organizational directory (Any Azure AD directory - Multitenant). Follow Microsoft best practices for multitenant applications, especially regarding security and permission scope.
5. Leave Redirect URI empty, this field isn’t required for OAuth2 Client Credentials. Click Register.
6. After the registration, the Application Overview page appears. Copy and securely store:

• Application (client) ID.
  • Directory (tenant) ID.

You will need these IDs later for the Send SMTP Email Node.

Create a Client Secret

1. In the created application, go to Manage > Certificates & secrets.
2. Click New client secret.
3. Enter the required information:
   • Description – for example, Cognigy SMTP Secret.
   • Expiration – specify the date according to your company’s security policy.
4. Click Add. Copy the appeared secret value and store it securely. You will need this secret later for the Send SMTP Email Node.

Configure API Permissions

1. Add the SMTP.SendAsApp permission to your Microsoft Entra application. Ensure admin consent is granted where required.
2. Register a Service Principal for your application.

Configure the Send SMTP Email Node

1. In the Send SMTP Email Node, select Microsoft 365 as the email service.
2. For the Authentication Method, select OAuth2 Client Credentials and click + to create a new connection.
3. In the connection configuration, fill in the required fields:
   • Connection Name — enter a unique name for the connection.
   • Client ID — enter the application (Client) ID from Microsoft Entra.
   • Client Secret — enter the secret value created under Certificates & Secrets from Microsoft Entra.
   • Scope — enter https://outlook.office365.com/.default
   • Token Endpoint URL — enter https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token and replace {tenant_id} with your Directory (tenant) ID from Microsoft Entra.
   • User — enter the email address of the sender mailbox. Make sure SMTP AUTH is activated for the user, and the user is granted the SMTP.SendAsApp permission.
4. Click Create to save the connection, then fill in the required fields for the email configuration, such as Recipient TO Email Addresses, Email Subject, and Email Content.

Troubleshooting