SuiteCRM Email Configuration: Complete SMTP & IMAP Setup Guide

Email is the backbone of CRM operations — notifications, workflow alerts, campaign emails, case auto-replies, and personal correspondence all depend on properly configured email settings. Yet email setup is one of the most common pain points SuiteCRM users face, with community forums full of “connection refused” and “SMTP not working” threads.

This guide walks you through every aspect of SuiteCRM email configuration — outbound SMTP, inbound IMAP, Gmail and Outlook setup, OAuth authentication, email templates, and troubleshooting — so your CRM sends and receives email reliably from day one.

Understanding SuiteCRM’s Email Architecture

SuiteCRM handles email through two separate configurations:

Outbound Email (SMTP) — This is how SuiteCRM sends emails: workflow notifications, campaign emails, case response templates, and personal emails from users. SMTP (Simple Mail Transfer Protocol) is configured at the system level for the entire CRM, and individual users can optionally set up personal outbound accounts.

Inbound Email (IMAP) — This is how SuiteCRM receives emails: monitoring mailboxes for incoming messages, auto-creating cases from support emails, and importing email conversations into contact records. IMAP (Internet Message Access Protocol) is the only inbound protocol SuiteCRM supports.

Both must be configured correctly for full email functionality.

Part 1: Configuring Outbound Email (SMTP)

System-Level SMTP Setup

The system outbound email account is used for all automated emails — workflow notifications, campaign sends, and system alerts. Here’s how to configure it:

Log into SuiteCRM as an Administrator. Navigate to Admin → Email Settings (under the Email section). You’ll see the system outbound email configuration panel.

Fill in these fields:

“From” Name: Enter your organization name (e.g., “TechEsperto CRM” or “Your Company”). This appears as the sender name on all outgoing system emails.

“From” Address: Enter a valid email address (e.g., crm@yourcompany.com). This is the sender address for system emails. Some SMTP providers require this to match the authenticated account.

Choose your Email provider: Click “Other” for manual SMTP configuration (recommended for full control). SuiteCRM also provides presets for Gmail and Microsoft Exchange.

SMTP Mail Server: Enter your SMTP server address. Common values include smtp.gmail.com (Gmail/Google Workspace), smtp.office365.com (Microsoft 365/Outlook), smtp.mail.yahoo.com (Yahoo), or your hosting provider’s SMTP server.

SMTP Port: Common ports are 587 (STARTTLS — recommended for most providers), 465 (SSL/TLS — used by some providers), and 25 (unencrypted — avoid in production, often blocked by hosting providers).

Use SMTP Authentication: Enable this (checked) for almost all SMTP providers. Enter the email account username (usually the full email address) and password.

SMTP Security: Select TLS for port 587 or SSL for port 465. Never use “None” in production.

Click Send Test Email to verify. Enter a test recipient address and check that the email arrives. If it does, save the configuration.

Gmail SMTP Configuration

Gmail is one of the most common SMTP providers for SuiteCRM. Here are the exact settings:

SMTP Mail Server: smtp.gmail.com. SMTP Port: 587. Use SMTP Authentication: Yes. Username: your full Gmail address (you@gmail.com or you@yourdomain.com for Workspace). Password: App Password (not your regular Gmail password). SMTP Security: TLS.

Critical note on Gmail App Passwords: Google requires App Passwords for applications that don’t support OAuth 2.0 natively. To generate one: go to your Google Account → Security → 2-Step Verification → App passwords. Generate a password for “Mail” on “Other (Custom name).” Use this 16-character password in SuiteCRM instead of your regular Gmail password.

If you’re using Google Workspace, your admin may need to enable “Less secure app access” or configure OAuth — see the OAuth section below.

Important: Gmail may block send attempts it considers suspicious, especially from new server IP addresses. If your test email fails, check your Gmail account for a “suspicious sign-in blocked” notification and approve the access.

Microsoft 365 / Outlook SMTP Configuration

SMTP Mail Server: smtp.office365.com. SMTP Port: 587. Use SMTP Authentication: Yes. Username: your full email address (you@yourdomain.com). Password: Your Microsoft 365 account password (or App Password if 2FA is enabled). SMTP Security: TLS.

Note: Microsoft has been deprecating Basic Authentication for Exchange Online. If Basic Auth is disabled in your tenant, you’ll need to configure OAuth 2.0 authentication instead — see the OAuth section below.

Amazon SES SMTP Configuration

For high-volume email sending (campaigns, mass notifications), Amazon SES provides reliable delivery at low cost.

SMTP Mail Server: email-smtp.us-east-1.amazonaws.com (or your region). SMTP Port: 587. Use SMTP Authentication: Yes. Username: Your SES SMTP username (from AWS Console → SES → SMTP Settings). Password: Your SES SMTP password. SMTP Security: TLS.

Note that AWS EC2 instances block port 25 by default. Use port 587 or request port 25 unblocking from AWS support.

Personal Outbound Email Accounts

Individual users can set up personal outbound email accounts to send emails from their own address rather than the system account. This is configured per user under their profile → Email Settings → Outbound Email. The SMTP settings follow the same format as the system configuration.

Part 2: Configuring Inbound Email (IMAP)

System Inbound Email (Group Mailboxes)

System inbound email accounts monitor shared mailboxes — like support@yourcompany.com or info@yourcompany.com — and can automatically create Cases, import emails, or distribute messages to assigned users.

Navigate to Admin → Inbound Email. Click “New Group Mail Account.” Configure these settings:

Name: A descriptive name (e.g., “Support Inbox” or “Sales Inquiries”).

Mail Server Address: Your IMAP server (e.g., imap.gmail.com, outlook.office365.com, or your hosting IMAP server).

Mail Server Protocol: IMAP (the only supported protocol).

Mail Server Port: 993 (IMAP over SSL — standard) or 143 (IMAP without SSL — not recommended).

Use SSL: Yes (for port 993). No (for port 143).

Username: The full email address of the mailbox.

Password: Account password or App Password.

Monitored Folders: Click SELECT to connect and choose which folders to monitor. At minimum, select the Inbox and Trash folders.

Auto Import: Check this to automatically create SuiteCRM records for all incoming emails. Imported emails appear in the History subpanel of related Contacts, Leads, or Accounts.

Auto-Create Cases: Enable this if you want incoming emails to automatically generate Case records — ideal for customer support operations. Set a default Case distribution method (round-robin or specific user) and select an auto-reply email template.

Gmail IMAP Settings

Mail Server Address: imap.gmail.com. Port: 993. Use SSL: Yes. Username: your@gmail.com. Password: App Password (same as SMTP).

Ensure IMAP is enabled in your Gmail settings: Gmail → Settings → See All Settings → Forwarding and POP/IMAP → Enable IMAP.

Microsoft 365 IMAP Settings

Mail Server Address: outlook.office365.com. Port: 993. Use SSL: Yes. Username: your@yourdomain.com. Password: Account password or App Password.

Personal Inbound Email Accounts

Individual users can set up their own email accounts to read and manage email within SuiteCRM. This is done through the Emails module → Settings → Mail Accounts → Add. The same IMAP settings apply.

Part 3: OAuth 2.0 Authentication (Modern Authentication)

Google and Microsoft are increasingly requiring OAuth 2.0 instead of Basic Authentication (username + password). SuiteCRM supports OAuth through External OAuth Connections.

Setting Up OAuth for Gmail / Google Workspace

Navigate to Admin → External OAuth Connections. Create a new connection with the Google provider. You’ll need to create OAuth credentials in Google Cloud Console: go to console.cloud.google.com → APIs & Services → Credentials → Create OAuth 2.0 Client ID. Enter the Client ID and Client Secret in SuiteCRM. Authorize the connection — SuiteCRM will redirect you to Google for consent.

Once configured, select this OAuth Connection when setting up inbound or outbound email accounts instead of entering a password.

Setting Up OAuth for Microsoft 365

The process is similar: register an application in Azure Active Directory (portal.azure.com → App Registrations), note the Client ID and Client Secret, configure redirect URIs, and add the OAuth connection in SuiteCRM’s External OAuth Connections panel.

OAuth setup can be tricky. If you’re not comfortable with Google Cloud Console or Azure AD, a SuiteCRM partner can handle this configuration for you.

Part 4: Email Templates

Email templates save time and ensure consistent communication. SuiteCRM supports templates for workflow emails, campaign emails, and case auto-replies.

Navigate to Emails → Email Templates (or Admin → Email Templates for system templates). Create a new template with a subject line, body content, and optional HTML formatting. Use merge variables to personalize templates — insert fields like contact name, account name, case number, opportunity amount, or any custom field.

Common templates to create: new lead acknowledgment, case created auto-reply, case resolved notification, meeting reminder, quote sent follow-up, workflow alert (e.g., deal stage changed), and campaign emails for marketing.

Templates are referenced by workflows when sending automated emails — setting up good templates early saves significant time later.

Part 5: Troubleshooting Common Email Issues

“Connection Refused” Errors

This typically means the SMTP/IMAP server is unreachable from your SuiteCRM server. Check that your hosting provider doesn’t block outbound ports 587, 465, or 993 (common on shared hosting and AWS EC2). Verify the server address and port are correct. Test connectivity from your server command line using telnet. Check firewall rules on your server.

“Authentication Failed” Errors

Your username or password is incorrect, or the email provider is blocking the connection. For Gmail, ensure you’re using an App Password, not your regular password. For Microsoft 365, verify Basic Auth isn’t disabled in your tenant. Check for “suspicious login” notifications in your email provider’s security settings. Try OAuth authentication instead of Basic Auth.

Emails Sending but Not Being Received

The email is likely being sent but landing in spam or being rejected by the recipient’s server. Verify your sending domain has proper SPF, DKIM, and DMARC DNS records. Check that the “From” address matches your domain’s authorized senders. Use a tool like mail-tester.com to check your email deliverability score. Consider using a dedicated SMTP service (Amazon SES, SendGrid) for better deliverability.

SuiteCRM Scheduler Not Processing Emails

Inbound email checking and campaign sends depend on the SuiteCRM Scheduler (cron job). Navigate to Admin → Schedulers and verify that “Check Inbound Mailboxes” and “Run Nightly Process Bounced Campaign Emails” are active and have run recently. Ensure your cron job is configured correctly — it should run every minute. Check the “Last ran successfully” timestamp to confirm the scheduler is executing.

Emails Not Linking to Contacts/Leads

SuiteCRM matches incoming emails to records based on the email address. If an incoming email’s sender address doesn’t match any Contact, Lead, or Account email field, it won’t auto-link. Ensure your contact records have accurate email addresses. Check that “Auto Import” is enabled on your inbound email account.

Best Practices for SuiteCRM Email

Use a dedicated sending domain. Don’t send CRM emails from a personal Gmail address. Use a domain-specific address (crm@yourcompany.com) with properly configured SPF, DKIM, and DMARC records.

Separate transactional and marketing email. Use your primary SMTP for workflow notifications and personal emails. Use a dedicated service like Amazon SES or SendGrid for campaign bulk sends — this protects your domain’s sending reputation.

Monitor bounce rates. High bounce rates damage your sending reputation. Use SuiteCRM’s campaign bounce tracking and clean your contact lists regularly.

Set up email archiving. Configure inbound email to auto-import all customer correspondence. This builds a complete communication history visible in the contact’s History subpanel — invaluable for sales teams and support teams.

Secure your email configuration. Store credentials securely. Use OAuth where possible. Rotate passwords regularly. Restrict system email account access to administrators only.

When to Get Professional Help

Email configuration touches multiple systems — your CRM, email provider, DNS records, hosting firewall, and authentication protocols. If any piece is misconfigured, emails silently fail. Common situations where professional SuiteCRM support saves hours of frustration include OAuth setup for Gmail or Microsoft 365, deliverability issues (emails going to spam), complex inbound email routing for multi-department case creation, campaign email setup with proper bounce handling, and integration with third-party email services.