Fix Odoo Mail Gateway Bounce Errors: Email Delivery and Fetchmail Issues

The Email Bounce Problem

Email is critical in Odoo — sales quotations, invoices, purchase orders, and internal communication all depend on it. When emails bounce, get rejected, or incoming emails are not processed, it disrupts business operations. The Odoo mail gateway handles both outgoing and incoming email, and each side has its own failure modes.

Common Error Messages

# Outgoing email failures:
WARNING odoo.addons.mail: Mail delivery failed
smtplib.SMTPRecipientsRefused: {'[email protected]': (550, b'5.1.1 The email account does not exist')}

smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted')

smtplib.SMTPSenderRefused: (553, b'5.1.8 Domain of sender address does not exist')

ConnectionRefusedError: [Errno 111] Connection refused  # SMTP server not reachable

# Incoming email failures:
ERROR odoo.addons.fetchmail: Failed to fetch mail from [email protected]
imaplib.IMAP4.error: [AUTHENTICATIONFAILED] Invalid credentials

WARNING odoo.addons.mail: Bounce received for message-id: <[email protected]>

Outgoing Email Fixes

Fix 1: SMTP Authentication

The most common issue. Modern email providers require app-specific passwords or OAuth.

# Gmail:
# 1. Enable 2FA on your Google account
# 2. Generate an App Password:
#    Google Account → Security → App passwords → Generate
# 3. Use the app password (not your regular password) in Odoo
#    Settings → Technical → Outgoing Mail Servers
#    SMTP Server: smtp.gmail.com
#    Port: 587
#    Security: TLS (STARTTLS)
#    Username: [email protected]
#    Password: [16-char app password]

# Microsoft 365:
# SMTP Server: smtp.office365.com
# Port: 587
# Security: TLS (STARTTLS)
# Username: [email protected]
# Password: your password (or app password if MFA enabled)
# NOTE: SMTP AUTH must be enabled for the mailbox in M365 admin

Fix 2: SPF, DKIM, and DMARC Records

Even if Odoo sends the email successfully, the recipient's mail server may reject it without proper DNS records.

# Check your domain's SPF record:
dig TXT yourdomain.com | grep spf

# Add SPF record to allow your SMTP server:
v=spf1 include:_spf.google.com ~all
# Or for a custom SMTP server:
v=spf1 ip4:YOUR.SERVER.IP ~all

# Check DKIM:
dig TXT google._domainkey.yourdomain.com

# Check DMARC:
dig TXT _dmarc.yourdomain.com

# Without these records, emails land in spam or get rejected

Fix 3: Bounce Alias Configuration

Odoo needs a bounce alias to handle delivery failure notifications.

# Settings → Technical → Parameters → System Parameters:
# Key: mail.bounce.alias
# Value: bounce (creates [email protected])

# Key: mail.catchall.alias
# Value: catchall

# Key: mail.catchall.domain
# Value: yourdomain.com

# These must match actual email addresses that route to your Odoo fetchmail

Fix 4: From Address Mismatch

Many SMTP providers reject emails where the "From" address does not match the authenticated user.

# In odoo.conf:
# Force the envelope sender to match the SMTP user:
email_from = [email protected]

# Or set it as a system parameter:
# Key: mail.default.from
# Value: notifications
# This sends from [email protected]

Incoming Email Fixes

Fix 5: Fetchmail Configuration

Odoo uses fetchmail to poll IMAP/POP3 servers for incoming emails.

# Settings → Technical → Incoming Mail Servers → Create
# Server Name: Gmail Incoming
# Server Type: IMAP
# Server: imap.gmail.com
# Port: 993
# SSL/TLS: checked
# Username: [email protected]
# Password: [app password — same as outgoing]

# Click "Test & Confirm" to verify the connection
# Set the poll interval (default 5 minutes)

Fix 6: Gmail IMAP Access

Gmail requires IMAP to be explicitly enabled.

# In Gmail Settings:
# 1. Go to Gmail → Settings → See all settings → Forwarding and POP/IMAP
# 2. Under IMAP Access: Enable IMAP
# 3. Save Changes

# If using Google Workspace:
# Admin Console → Apps → Google Workspace → Gmail → End User Access
# Ensure IMAP is enabled for the organizational unit

Fix 7: Fetchmail Cron Not Running

Incoming email polling depends on the fetchmail cron job.

# Check if the cron is active:
# Settings → Technical → Automation → Scheduled Actions
# Search for: "Fetchmail" or "Mail: Fetchmail Service"
# Ensure it is Active and has a reasonable interval

# In Odoo shell:
cron = env['ir.cron'].sudo().search([('name', 'ilike', 'fetchmail')])
for c in cron:
    print(f'{c.name}: active={c.active}, interval={c.interval_number} {c.interval_type}')

# Note: cron jobs only run when workers > 0 in production

Diagnosing Email Issues

# 1. Check mail queue:
# Settings → Technical → Email → Emails
# Filter by Status: Outgoing / Exception / Bounce

# 2. Check individual email for error message:
# Open the email record → scroll to bottom → "Failure Reason"

# 3. Test SMTP from command line:
python3 -c "
import smtplib
server = smtplib.SMTP('smtp.gmail.com', 587)
server.starttls()
server.login('[email protected]', 'app-password')
print('SMTP auth successful')
server.quit()
"

# 4. Check Odoo logs for mail errors:
grep -i 'mail\|smtp\|fetchmail\|bounce' /var/log/odoo/odoo-server.log | tail -30

Common Bounce Codes