Implementing IMAP and SMTP Gateway Configuration for Genesys Cloud Email Routing

How-To-Articles
1

Implementing IMAP and SMTP Gateway Configuration for Genesys Cloud Email Routing

What This Guide Covers

You are configuring an email channel in Genesys Cloud by connecting your organization’s IMAP mailbox as an inbound source and SMTP server as an outbound relay. When complete, emails arriving at support@yourcompany.com will be polled by Genesys Cloud every 60 seconds, converted into Genesys interactions, routed to the appropriate agent queue by an Architect inbound email flow, and replied to by agents directly within the Agent Desktop-with the reply transmitted via SMTP and appearing to customers as a normal email from your corporate address. This replaces agents manually checking a shared inbox in Outlook or Gmail with a fully queue-managed, SLA-tracked email channel.

Prerequisites, Roles & Licensing

  • Genesys Cloud: CX 2 or 3 with the Digital channels add-on.
  • Permissions required:
    • Routing > Email Domain > Add
    • Admin > Integration > Edit
  • Mailbox requirements:
    • An IMAP-capable mailbox with IMAP access enabled (Gmail, Microsoft 365, on-premise Exchange, or custom SMTP/IMAP server).
    • If using Microsoft 365: Modern Authentication (OAuth2) is now required - Basic Auth is deprecated. Configure the Genesys Cloud Microsoft 365 OAuth integration first.
    • If using Gmail: Enable “Allow less secure apps” (for App Passwords) OR configure OAuth2 service account access.
  • DNS access: You need to add an MX record or forwarding rule to ensure inbound email is delivered to the mailbox Genesys polls.

The Implementation Deep-Dive

1. The Email Routing Architecture

[Customer sends email to support@yourcompany.com]
    |
    v
[Your mail server receives email → stores in IMAP mailbox]
    |
    v (Genesys polls every 60 seconds via IMAP IDLE/polling)
[Genesys Cloud Email Integration reads new messages]
    |
    v
[Email → Genesys Interaction → Architect Inbound Email Flow]
    |
    v
[Route to Queue based on subject, from address, or custom classification]
    |
    v
[Agent receives email in ACD queue → replies in Agent Desktop]
    |
    v (Genesys sends reply via configured SMTP server)
[Customer receives reply from support@yourcompany.com]

2. Domain Configuration (DNS + Genesys)

First, add your email domain in Genesys Cloud Admin:

  1. Navigate to Admin → Email → Email Domains
  2. Click Add Domain
  3. Enter your domain: yourcompany.com
  4. Genesys generates DNS records for you to add:
    • CNAME: genesys-mail.yourcompany.com → email.mypurecloud.com
    • MX record (if using Genesys Cloud-managed inbound): @yourcompany.com MX 10 inbound.mypurecloud.com
    • SPF TXT record: v=spf1 include:mypurecloud.com ~all

Important: If you already have an MX record for your domain (pointing to Microsoft 365 or Google), do not replace it. Instead, configure email forwarding from your existing mailbox to the Genesys-managed inbound address. This avoids mail delivery disruption.

3. Connecting an IMAP Mailbox (Microsoft 365 OAuth2)

Microsoft deprecated Basic Auth for Exchange/IMAP in October 2022. Configure OAuth2:

# This script creates an Azure AD App Registration for Genesys Cloud IMAP access
# Run once during setup, then provide the credentials to the Genesys integration UI

import msal
import json

TENANT_ID = "your-azure-tenant-id"
CLIENT_ID = "your-azure-app-client-id"  
CLIENT_SECRET = "your-azure-app-client-secret"

# The app needs Mail.Read and Mail.Send delegated permissions
# (or Application permissions for non-interactive service accounts)
SCOPES = ["https://graph.microsoft.com/Mail.Read", "https://graph.microsoft.com/Mail.Send"]

app = msal.ConfidentialClientApplication(
    CLIENT_ID,
    authority=f"https://login.microsoftonline.com/{TENANT_ID}",
    client_credential=CLIENT_SECRET
)

# Acquire token (client credentials = service account, not user-delegated)
result = app.acquire_token_for_client(
    scopes=["https://graph.microsoft.com/.default"]  # Client credential flow
)

if "access_token" in result:
    print(f"✓ Token acquired. Expires in: {result.get('expires_in')} seconds")
    print(f"Token (store in Genesys integration): {result['access_token'][:40]}...")
else:
    print(f"✗ Error: {result.get('error_description')}")

In Genesys Cloud Admin:

  1. Admin → Email → Email Domains → [Your Domain] → Inbound Routes
  2. Add an inbound route for support@yourcompany.com
  3. Select Microsoft 365 as the server type
  4. Enter Client ID, Client Secret, Tenant ID
  5. Set polling interval: 60 seconds (minimum for CX 2/3)

4. SMTP Configuration for Outbound (Replies)

Genesys Cloud uses SMTP to send replies. Configure the outbound SMTP settings:

For Microsoft 365 SMTP:

SMTP Server: smtp.office365.com
Port: 587 (STARTTLS)
Username: support@yourcompany.com (the mailbox account)
Authentication: OAuth2 (preferred) or App Password
Encryption: STARTTLS
From Address: support@yourcompany.com
Reply-To: support@yourcompany.com

For Gmail SMTP:

SMTP Server: smtp.gmail.com
Port: 465 (SSL) or 587 (STARTTLS)
Username: support@yourcompany.com
Authentication: App Password (Google Workspace)
From Address: support@yourcompany.com

Generate a Google App Password: Google Admin Console → Security → 2-Step Verification → App Passwords. Name it “Genesys Cloud SMTP”.

5. Architect Inbound Email Flow

Once the IMAP integration is polling, configure an Architect Inbound Email flow to route messages:

[Inbound Email]
    |
    v
[Get Data: from.address, subject, body_preview]
    |
    v
[Decision: subject contains "[URGENT]"?]
    |
    |-- YES → [Set Priority: 10] → [Transfer to Email Queue: Priority Support]
    |
    |-- NO → [Decision: from.domain is "enterprise-client.com"?]
                |
                |-- YES → [Transfer to Email Queue: Enterprise Support]
                |
                |-- NO → [Data Action: ML Classification API → category]
                              |
                              |-- "billing" → [Transfer to Email Queue: Billing]
                              |-- "technical" → [Transfer to Email Queue: Tech Support]
                              |-- default → [Transfer to Email Queue: General Support]

Set an Automatic Response action at the start of the flow to send an instant acknowledgment:

Subject: Re: {{interaction.email.subject}}
Body: Thank you for contacting us. Your request has been received and 
assigned reference number {{interaction.id}}. We aim to respond within 
4 business hours. 
- The Support Team

6. Auto-Response Suppression for Loop Prevention

A critical edge case: Outlook/Exchange Out-of-Office replies and automated system emails can trigger infinite loops if Genesys creates interactions from them and agents reply, generating more auto-replies.

Implement header-based auto-response detection in the Architect flow:

[Check Email Headers Data Action]
    |
    v (HTTP GET custom header analysis via Data Action)
[Decision: X-Auto-Response-Suppress header exists?]
    |-- YES → [Disconnect (discard silently)]
[Decision: Auto-Submitted header is "auto-replied"?]
    |-- YES → [Disconnect]
[Decision: subject starts with "Delivery Status Notification"?]  
    |-- YES → [Disconnect]

Alternatively, filter at the IMAP polling layer by configuring keyword exclusion rules in the Genesys Email integration settings.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Emails in Genesys Show as HTML Source Instead of Rendered Content

Genesys Cloud renders HTML email bodies in the agent’s email interaction view. If the agent sees raw <html> tags, the email was delivered as text/html with a non-standard MIME structure.
Solution: Check the email’s Content-Type header. Emails with multipart/alternative bodies (both plain text and HTML parts) render correctly. Emails sent with only text/html and missing the boundary declarations may not. Ensure your corporate mail server is not stripping MIME boundaries.

Edge Case 2: IMAP Polling Delay Exceeds 60 Seconds

Customer emails take 4-5 minutes to appear in Genesys. The expected SLA is under 2 minutes.
Solution: Verify the IMAP connection is using IMAP IDLE (push-based notification) rather than pure polling. IDLE-capable servers notify Genesys of new messages immediately. If your server doesn’t support IDLE, reduce the polling interval to 30 seconds in the integration settings. Also check whether your IMAP server applies per-connection rate limits that might slow Genesys’s polling.

Edge Case 3: Reply “From” Address Appears as Genesys Internal Address

Agents send replies but customers receive them from noreply@mypurecloud.com instead of support@yourcompany.com.
Solution: Verify the From Address field in the SMTP integration settings is set to support@yourcompany.com. Also confirm the email domain is verified (green checkmark) in Admin → Email → Email Domains. If SPF/DKIM records are missing, the customer’s mail server may strip the From header and substitute the envelope sender.

Official References