Skip to main content
Frappe Helpdesk can receive tickets via email and send responses from your support email addresses. This guide covers email account setup, configuration, and troubleshooting.

​
Email Integration Overview

Email integration enables:
  • Automatic Ticket Creation: Incoming emails create tickets automatically
  • Email Threading: Replies maintain conversation context
  • Outbound Email: Send responses from your support email address
  • Multiple Accounts: Support multiple email addresses for different teams
  • Service Provider Support: Pre-configured for Gmail, Outlook, Yahoo, and more

​
Supported Email Services

Frappe Helpdesk includes pre-configured settings for popular email providers (see helpdesk/api/settings/email.py:74-148):
  • Gmail: Google Workspace and personal Gmail accounts
  • Outlook: Microsoft 365 and Outlook.com
  • Yahoo Mail: Yahoo email accounts
  • Yandex Mail: Yandex email service
  • Frappe Mail: Native integration with Frappe Mail
  • SendGrid: Transactional email service
  • SparkPost: Email delivery platform
  • Custom IMAP/SMTP: Any email provider with IMAP/SMTP access

​
Prerequisites

Before setting up email integration:
1

Prepare Email Account

  • Create a dedicated email address for support (e.g., [email protected])
  • Don’t use personal email addresses
  • Ensure account has IMAP and SMTP access enabled
2

Enable IMAP/SMTP

For most providers:
  • Enable IMAP in email settings
  • Enable “less secure apps” or app-specific passwords
  • Note down IMAP and SMTP server addresses
3

Generate App Password (if required)

For Gmail and some other providers:
  • Enable 2-factor authentication
  • Generate an app-specific password
  • Use this instead of your regular password

​
Adding an Email Account

1

Navigate to Email Settings

Go to Settings > Email Accounts in the Frappe Helpdesk agent interface.
2

Click Add Email Account

Select “Add Email Account” to start the configuration wizard.
3

Choose Email Service

Select your email provider from the list:
  • Gmail
  • Outlook
  • Yahoo
  • Frappe Mail
  • Custom (for other providers)
4

Enter Basic Information

Fill in the required fields:
  • Email Account Name: Descriptive name (e.g., “Support Email”)
  • Email ID: Your email address (e.g., [email protected])
  • Password: Email password or app-specific password
5

Configure Incoming Email

Set incoming email options:
  • Enable Incoming: Check to receive emails
  • Default Incoming: Make this the default for receiving emails
  • Email Sync Option: Choose “ALL” to sync all emails
  • Initial Sync Count: Number of recent emails to sync (default: 100)
6

Configure Outgoing Email

Set outgoing email options:
  • Enable Outgoing: Check to send emails
  • Default Outgoing: Make this the default for sending emails
  • Track Email Status: Enable delivery tracking
7

Test and Save

Click “Save” to validate the connection. The system will:
  • Test IMAP connection for incoming email
  • Test SMTP connection for outgoing email
  • Display success or error messages

​
Service-Specific Configuration

​
Gmail

1

Enable IMAP in Gmail

  1. Go to Gmail Settings > Forwarding and POP/IMAP
  2. Enable IMAP
  3. Save changes
2

Generate App Password

  1. Go to Google Account > Security
  2. Enable 2-Step Verification
  3. Go to App Passwords
  4. Generate password for “Mail” application
  5. Copy the 16-character password
3

Configure in Helpdesk

  • Service: Gmail
  • Email ID: [email protected]
  • Password: Paste the app password
  • Use SSL: Enabled (automatic)
  • Email Server: imap.gmail.com (automatic)
  • SMTP Server: smtp.gmail.com (automatic)
Pre-configured settings (from email.py:95-99): 
"GMail": {
    "email_server": "imap.gmail.com",
    "use_ssl": 1,
    "smtp_server": "smtp.gmail.com",
}

​
Outlook / Microsoft 365

1

Enable IMAP

  1. Go to Outlook Settings > Mail > Sync email
  2. Enable IMAP
  3. Save settings
2

Use App Password (if 2FA enabled)

  1. Go to Microsoft Account Security
  2. Create app password
  3. Use for Helpdesk configuration
3

Configure in Helpdesk

  • Service: Outlook
  • Email ID: [email protected] or [email protected]
  • Password: Account password or app password
  • Use SSL: Enabled (automatic)
  • Email Server: imap-mail.outlook.com (automatic)
  • SMTP Server: smtp-mail.outlook.com (automatic)
Pre-configured settings: 
"Outlook": {
    "email_server": "imap-mail.outlook.com",
    "use_ssl": 1,
    "smtp_server": "smtp-mail.outlook.com",
}

​
Yahoo Mail

1

Generate App Password

  1. Go to Yahoo Account Security
  2. Turn on 2-Step Verification
  3. Generate app password for “Mail”
  4. Copy the password
2

Configure in Helpdesk

  • Service: Yahoo
  • Email ID: [email protected]
  • Password: App password
  • Use SSL: Enabled (automatic)
  • Email Server: imap.mail.yahoo.com (automatic)
  • SMTP Server: smtp.mail.yahoo.com (automatic)
  • SMTP Port: 587 (automatic)

​
Frappe Mail

Frappe Mail provides native integration with special features:
1

Get Frappe Mail Credentials

From your Frappe Mail account:
  • API Key
  • API Secret
  • Frappe Mail Site URL
2

Configure in Helpdesk

  • Service: Frappe Mail
  • Email ID: [email protected]
  • Frappe Mail Site: Your Frappe Mail site URL
  • API Key: From Frappe Mail
  • API Secret: From Frappe Mail
  • Append To: HD Ticket (automatic)
Frappe Mail uses API-based sync instead of IMAP/SMTP (see email.py:37-41): 
if service == "Frappe Mail":
    email_doc.api_key = data.get("api_key")
    email_doc.api_secret = data.get("api_secret")
    email_doc.frappe_mail_site = data.get("frappe_mail_site")
    email_doc.append_to = "HD Ticket"

​
Custom IMAP/SMTP

For providers not listed:
1

Gather Server Information

Get from your email provider:
  • IMAP server address and port
  • SMTP server address and port
  • SSL/TLS requirements
2

Configure in Helpdesk

  • Service: Custom
  • Email ID: [email protected]
  • Password: Email password
  • Email Server: IMAP server (e.g., mail.yourhost.com)
  • Incoming Port: Usually 993 (SSL) or 143 (STARTTLS)
  • SMTP Server: SMTP server
  • SMTP Port: Usually 465 (SSL) or 587 (TLS)
  • Use SSL: Enable if required
  • Use STARTTLS: Enable if required
  • Use TLS: Enable if required

​
Email Sync Configuration

​
Sync Options

Control which emails are synced:
  • ALL: Sync all emails (read and unread)
  • UNSEEN: Only sync unread emails
Use “ALL” for initial setup to ensure no tickets are missed. Switch to “UNSEEN” after initial sync for efficiency.

​
Initial Sync Count

Defines how many recent emails to sync on first connection:
  • Default: 100 emails
  • Increase for accounts with high volume
  • Lower for testing or new accounts
Implementation in email.py:27-28: 
"email_sync_option": "ALL",
"initial_sync_count": 100,

​
IMAP Folder Configuration

Specify which folders to monitor:
1

Add IMAP Folders

For non-Frappe Mail services, configure folders:
  • Folder Name: Usually “INBOX”
  • Append To: HD Ticket
2

Monitor Multiple Folders

Add rows for additional folders:
  • INBOX → HD Ticket
  • Support → HD Ticket
  • Urgent → HD Ticket (with high priority rule)
Implementation: email.py:60-62

​
Auto-Generated Email Filtering

The system automatically ignores auto-generated emails to prevent loops: 
# From helpdesk/overrides/email_account.py:21-23
if _msg.get("X-Auto-Generated"):
    continue  # Skip auto-generated emails
This prevents:
  • Out-of-office replies from creating tickets
  • Email feedback notifications from creating loops
  • System-generated emails from becoming tickets

​
Ticket Creation from Email

​
How It Works

1

Email Arrives

Email is received in the monitored IMAP folder.
2

Email is Fetched

Helpdesk syncs emails based on schedule (usually every few minutes).
3

Ticket is Created

System creates a new HD Ticket:
  • Subject: Email subject line
  • Description: Email body (HTML preserved)
  • Raised By: Sender email address
  • Contact: Auto-created or linked if exists
  • Attachments: Email attachments are linked
4

Contact and Customer Linking

System automatically:
  • Creates Contact if it doesn’t exist
  • Links to Customer if Contact is associated
  • Sets create_contact: 1 in email account config
5

Assignment

Ticket is assigned based on assignment rules.
6

Acknowledgement (Optional)

If enabled, customer receives acknowledgement email.

​
Email Threading

Replies to tickets maintain conversation context:
  • In-Reply-To Header: Links reply to original ticket
  • References Header: Maintains email thread
  • Subject Prefix: “Re:” indicates reply
When customer replies:
  1. System identifies existing ticket by message-id
  2. Adds reply as Communication on the ticket
  3. Updates last_customer_response timestamp
  4. Reopens ticket if status was resolved

​
Sending Email from Tickets

​
Composing Responses

1

Open Ticket

Navigate to the ticket you want to respond to.
2

Write Response

Use the email editor:
  • Compose your message
  • Use saved replies for common responses
  • Attach files if needed
  • Format with rich text editor
3

Send Email

Click send. The system:
  • Sends via configured email account
  • Maintains email threading
  • Updates ticket timestamps
  • Logs communication

​
Email Account Selection

Outbound emails are sent from:
  1. Default Outgoing Account: Marked as default
  2. Ticket’s Email Account: If ticket came via specific email
  3. System Default: Fallback if no default is set

​
Email Customization

Customize email content in HD Settings:

​
Acknowledgement Email

Sent when ticket is created via email:
  • Enable: Settings > Email Customizations > Send Acknowledgement Email
  • Content: Customize the acknowledgement_email_content field
  • Template Variables: Use {{ doc.subject }}, {{ doc.name }}, etc.

​
Feedback Email

Sent when ticket is resolved:
  • Enable: Settings > Email Customizations > Enable Email Ticket Feedback
  • Status Trigger: Send on specific status or “Closed”
  • Content: Customize feedback_email_content field
  • Feedback Link: Automatically includes feedback URL
Implementation: hd_settings.json:68-74

​
Reply Notification

Notify customers when agents reply:
  • Enable Reply Email to Agent: Notify agent when customer replies
  • Enable Reply Email via Agent: Notify customer when agent replies
  • Customize Content: Tailor notification messages

​
Advanced Configuration

​
SSL/TLS Settings

Control encryption:
  • Use SSL: SSL encryption for IMAP (port 993)
  • Use TLS: TLS encryption for SMTP (port 587)
  • Use STARTTLS: STARTTLS for IMAP
  • Use SSL for Outgoing: SSL for SMTP (port 465)

​
Certificate Validation

  • Validate SSL Certificate: Verify IMAP server certificate
  • Validate SSL Certificate for Outgoing: Verify SMTP server certificate
Disable only for self-signed certificates in development.

​
Authentication

  • Login ID: Use different login ID than email address
  • No SMTP Authentication: Disable for servers that don’t require it
  • ASCII Encode Password: Enable for special characters

​
Email Headers

Custom email headers are automatically added: 
# From hd_ticket.py:171
email_headers={"X-Auto-Generated": "hd-email-feedback"}
This ensures feedback emails don’t create new tickets.

​
Troubleshooting

​
Email Account Not Syncing

Issue: Emails aren’t creating tickets Solutions:
  1. Check email account is enabled
  2. Verify IMAP credentials are correct
  3. Check IMAP folder name is correct
  4. Review error log for connection errors
  5. Test with a manual sync
  6. Verify firewall allows IMAP connections

​
Authentication Errors

Issue: “Authentication failed” errors Solutions:
  1. Verify password is correct
  2. Use app-specific password if 2FA is enabled
  3. Enable “less secure apps” (if applicable)
  4. Check if account is locked
  5. Verify email address format

​
SSL/TLS Errors

Issue: SSL certificate validation errors Solutions:
  1. Enable “Use SSL” for SSL connections
  2. Use correct port (993 for SSL, 143 for STARTTLS)
  3. Disable certificate validation for self-signed certs
  4. Update server time if clock skew error
  5. Check firewall allows SSL connections

​
Outgoing Email Not Sending

Issue: Responses don’t reach customers Solutions:
  1. Check SMTP credentials
  2. Verify SMTP port (587 for TLS, 465 for SSL)
  3. Enable “Use TLS” or “Use SSL”
  4. Check email account has “Enable Outgoing” checked
  5. Review SMTP error logs
  6. Verify SPF/DKIM records for domain

​
Duplicate Tickets

Issue: Same email creates multiple tickets Solutions:
  1. Check message-id tracking
  2. Verify email threading is working
  3. Review sync settings (use UNSEEN instead of ALL)
  4. Check for multiple email accounts monitoring same inbox

​
Email Not Threading

Issue: Replies create new tickets instead of updating existing Solutions:
  1. Ensure In-Reply-To header is present
  2. Check email client preserves threading headers
  3. Verify message-id is being tracked
  4. Review Communication records for correct reference

​
Best Practices

​
Email Account Management

  1. Dedicated Addresses: Use separate email addresses for each team or department
  2. Clear Naming: Use descriptive account names (e.g., “Technical Support”, “Billing Team”)
  3. Regular Monitoring: Check email account status and sync logs
  4. Backup Credentials: Store credentials securely
  5. Test Regularly: Send test emails to verify sync is working

​
Security

  1. App Passwords: Always use app-specific passwords for 2FA accounts
  2. SSL/TLS: Enable encryption for all connections
  3. Certificate Validation: Keep enabled in production
  4. Password Rotation: Change passwords regularly
  5. Access Control: Limit who can modify email account settings

​
Performance

  1. Sync Frequency: Balance between responsiveness and server load
  2. Initial Sync: Start with lower count, increase if needed
  3. Folder Monitoring: Only monitor necessary folders
  4. Archive Old Emails: Clean up inbox regularly
  5. Error Handling: Monitor logs for sync errors

​
Email Content

  1. Professional Templates: Customize email templates to match brand
  2. Clear Subject Lines: Ensure subject indicates purpose
  3. Signature: Include contact information and support hours
  4. Unsubscribe: Provide opt-out for notification emails
  5. Mobile-Friendly: Test emails on mobile devices

Build docs developers (and LLMs) love

Get started for freeTalk to us