SMTP integration allows you to connect any SMTP-compatible email service to Notifuse, supporting both traditional password authentication and modern OAuth2 for Microsoft 365 and Gmail.
Configuration
Navigate to Settings → Integrations → Add Integration → SMTP.
Basic Settings
| Field | Description | Example |
|---|
| Integration Name | Display name for this SMTP configuration | Company SMTP |
| SMTP Host | SMTP server hostname | smtp.gmail.com |
| SMTP Port | SMTP server port number | 587 |
| Use TLS | Enable TLS encryption (recommended) | On |
Authentication Type
Notifuse supports two authentication methods:
| Type | Description | Use Case |
|---|
| Basic Auth | Traditional username/password authentication | Most SMTP servers, app passwords |
| OAuth2 | Modern token-based authentication | Microsoft 365, Gmail (required since 2024) |
Basic Authentication
For traditional SMTP servers or services that support app passwords.
| Field | Description | Example |
|---|
| SMTP Username | Authentication username | [email protected] |
| SMTP Password | Authentication password | your-app-password |
OAuth2 Authentication
OAuth2 is required for Microsoft 365 and Gmail since they have deprecated basic authentication.
Microsoft 365 OAuth2
Microsoft 365 uses the Client Credentials Flow for server-to-server authentication.
Prerequisites
- Microsoft 365 Business account (not personal Outlook.com)
- Azure AD admin access
- Exchange Online admin access
Step 1: Register Azure AD Application
- Go to Azure Portal → Azure Active Directory → App registrations
- Click New registration
- Enter a name (e.g., “Notifuse SMTP”)
- Select Accounts in this organizational directory only (Single tenant)
- Click Register
- Note the Application (client) ID and Directory (tenant) ID
Step 2: Create Client Secret
- In your app registration, go to Certificates & secrets
- Click New client secret
- Add a description and select expiry period
- Click Add
- Copy the secret value immediately (it won’t be shown again)
Step 3: Add API Permission
- Go to API permissions → Add a permission
- Select APIs my organization uses
- Search for Office 365 Exchange Online
- Select Application permissions
- Check SMTP.SendAsApp
- Click Add permissions
- Click Grant admin consent for [Your Organization]
Step 4: Register Service Principal in Exchange Online
This step is critical and often missed. Connect to Exchange Online PowerShell:
# Install module if needed
Install-Module -Name ExchangeOnlineManagement
# Connect to Exchange Online
Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com
# Register the service principal
New-ServicePrincipal -AppId <Application-Client-ID> -ObjectId <Object-ID>
Common Mistake: The ObjectId must be from Enterprise Applications, NOT from App Registrations.To find the correct Object ID:
- Go to Azure Portal → Microsoft Entra ID → Enterprise Applications
- Search for your app name
- Copy the Object ID from the Overview page
Step 5: Grant Mailbox Permission
Grant the service principal permission to send as a specific mailbox:
# Grant full access to the mailbox
Add-MailboxPermission -Identity "[email protected]" -User <Object-ID> -AccessRights FullAccess
# Grant send-as permission
Add-RecipientPermission -Identity "[email protected]" -Trustee <Object-ID> -AccessRights SendAs
Step 6: Enable SMTP AUTH on the Mailbox
SMTP AUTH must be enabled on the sending mailbox. This can be done via Microsoft 365 Admin Center or PowerShell:
Option A: Microsoft 365 Admin Center
- Go to Users → Active users
- Select the sender user
- Click Mail tab → Manage email apps
- Check Authenticated SMTP
- Click Save changes
Option B: PowerShell
# Enable SMTP AUTH for the mailbox
Set-CASMailbox -Identity "[email protected]" -SmtpClientAuthenticationDisabled $false
If Security Defaults is enabled in your Microsoft Entra tenant, SMTP AUTH is blocked organization-wide. You may need to disable Security Defaults or use Conditional Access policies instead.
| Field | Value |
|---|
| SMTP Host | smtp.office365.com |
| SMTP Port | 587 |
| Use TLS | On |
| Auth Type | OAuth2 |
| OAuth2 Provider | Microsoft |
| Username | Sender email (e.g., [email protected]) |
| Tenant ID | Your Azure AD Directory (tenant) ID |
| Client ID | Application (client) ID from Azure |
| Client Secret | Secret value from Step 2 |
The Username must match the mailbox you granted permissions to in Step 5.
Gmail OAuth2
Gmail uses the Refresh Token Flow for authentication.
Prerequisites
- Google account (personal Gmail or Google Workspace)
- Google Cloud Console access
- Terminal with
curl installed
Step 1: Create Google Cloud Project
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API:
- Go to APIs & Services → Library
- Search for “Gmail API” and enable it
- Go to APIs & Services → OAuth consent screen
- Select External user type (or Internal for Workspace)
- Fill in app information:
- App name: “Notifuse” (or your choice)
- User support email: Your email
- Developer contact: Your email
- Click Save and Continue
- On the Scopes page, click Add or Remove Scopes
- Add scope:
https://mail.google.com/
- Click Save and Continue
- On Test users page, add your Gmail address
- Click Save and Continue to complete the wizard
Step 3: Publish Your App (Required for Long-Lived Tokens)
Critical: Apps in “Testing” mode have refresh tokens that expire after 7 days. To get permanent refresh tokens, you must publish your app.
- Go to APIs & Services → OAuth consent screen
- Click Publish App
- Confirm by clicking Confirm
Your app status will change from “Testing” to “In production”.
No Google Verification Needed for Personal UsePublishing your app does NOT require Google verification if:
- You have fewer than 100 users
- You’re using it for personal/internal purposes
You may see an “unverified app” warning when authorizing - simply click Advanced → Go to [App Name] (unsafe) to proceed. Step 4: Create OAuth Credentials
- Go to APIs & Services → Credentials
- Click Create Credentials → OAuth client ID
- Select Web application
- Name it (e.g., “Notifuse SMTP”)
- Under Authorized redirect URIs, click Add URI
- Enter:
http://localhost
- Click Create
- A dialog will show your Client ID and Client Secret - save both
Step 5: Get Authorization Code
Open this URL in your browser, replacing YOUR_CLIENT_ID with your actual Client ID:
https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=https://mail.google.com/&response_type=code&access_type=offline&prompt=consent
scope=https://mail.google.com/ - Required for SMTP accessaccess_type=offline - Required to receive a refresh tokenprompt=consent - Forces Google to return a new refresh token
After signing in and granting permission, your browser will redirect to something like:
http://localhost/?code=4/0AQSTgQF...LONG_CODE...&scope=https://mail.google.com/
code value (everything between code= and &scope).
If the code contains %2F, replace it with / before using it.
Step 6: Exchange Code for Refresh Token
Run this curl command in your terminal, replacing the placeholders:
curl -X POST https://oauth2.googleapis.com/token \
-d "code=YOUR_AUTHORIZATION_CODE" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "redirect_uri=http://localhost" \
-d "grant_type=authorization_code"
{
"access_token": "ya29.a0AfH6SMBx...",
"expires_in": 3599,
"refresh_token": "1//0eHusbKw...",
"scope": "https://mail.google.com/",
"token_type": "Bearer"
}
Save your refresh_token immediately! Google only returns the refresh token on the first authorization. If you lose it, you’ll need to revoke access and re-authorize.
| Field | Value |
|---|
| SMTP Host | smtp.gmail.com |
| SMTP Port | 587 |
| Use TLS | On |
| Auth Type | OAuth2 |
| OAuth2 Provider | Google |
| Username | Your Gmail address |
| Client ID | Client ID from Step 4 |
| Client Secret | Client Secret from Step 4 |
| Refresh Token | Refresh token from Step 6 |
Refresh Token Lifetime
With a published app, your refresh token will remain valid indefinitely, unless:
| Condition | Result |
|---|
| Token unused for 6 months | Token expires |
| You change your Google password | Token is revoked |
| You exceed 50 refresh tokens per client | Oldest token is automatically revoked |
| You manually revoke access at myaccount.google.com/permissions | Token is revoked |
If your token becomes invalid, repeat Steps 5-6 to generate a new refresh token.
Senders List
Add sender addresses that can be used with this SMTP integration:
| Field | Description | Example |
|---|
| Name | Display name for the sender | Support Team |
| Email | Sender email address | [email protected] |
Usage Types
Configure how this SMTP integration will be used:
| Option | Description |
|---|
| Use for Transactional | Password resets, order confirmations, notifications |
| Use for Marketing | Newsletters, promotional campaigns, announcements |
Limitations
SMTP integrations have the following limitations:
- No delivery webhooks: SMTP does not provide real-time delivery status updates
- No bounce notifications: No automatic notifications when emails bounce
- No complaint tracking: No webhooks for spam reports or abuse complaints
Notifuse automatically adds open and click tracking to all emails, regardless of the email provider used.
Common SMTP Servers
| Provider | Host | Port | TLS | Auth Type |
|---|
| Gmail | smtp.gmail.com | 587 | Yes | OAuth2 (required) |
| Microsoft 365 | smtp.office365.com | 587 | Yes | OAuth2 (required) |
| Amazon SES | email-smtp.region.amazonaws.com | 587 | Yes | Basic Auth |
| SendGrid | smtp.sendgrid.net | 587 | Yes | Basic Auth |
| Mailgun | smtp.mailgun.org | 587 | Yes | Basic Auth |
Gmail and Microsoft 365 have deprecated basic authentication. You must use OAuth2 for these providers.
Troubleshooting
Microsoft 365: “535 5.7.3 Authentication unsuccessful”
This error usually means:
- Service principal not registered in Exchange Online (Step 4)
- Mailbox permissions not granted (Step 5)
- Username doesn’t match the permitted mailbox
Gmail: “unauthorized_client”
This error means:
- Refresh token was generated with different Client ID/Secret
- Regenerate the refresh token using your current credentials
Gmail: “invalid_grant”
This error means:
- Refresh token has expired (7 days in Testing mode)
- User changed their Google password
- Token was revoked or exceeded the 50-token limit
Solution: Generate a new refresh token following Step 4.
Testing
Click Test Integration to send a test email and verify your configuration. 