How Odoo Sends and Receives Email#
Odoo uses two independent systems for email:
- Outgoing: Odoo's mail queue sends messages through a configured SMTP server (
ir.mail_server) - Incoming: a fetchmail daemon polls a mailbox or Odoo receives inbound messages via an alias domain catch-all address
The two systems are independent. You can configure outgoing without incoming (most deployments do), or vice versa.
Outgoing Mail Server#
Go to Settings → Technical → Email → Outgoing Mail Servers.
Key fields:
- SMTP Server / Port: your mail relay host (e.g., smtp.gmail.com:587, or your own relay)
- Connection Security: TLS/STARTTLS for port 587; SSL for port 465; None for local relays
- Username / Password: SMTP credentials
- Priority: lower number = higher priority; Odoo picks the lowest-priority server that matches the sending company
Testing#
After saving, click Test Connection. If the test fails, check firewall rules (outbound 587/465 may be blocked on cloud providers) and SMTP credentials.
Per-company Outgoing Server#
Assign a server to a specific company in the Company field. When a company is set, Odoo uses that server only for emails originating from that company. Leave blank for a shared server.
Incoming Mail: Fetchmail#
Go to Settings → Technical → Email → Incoming Mail Servers.
Fetchmail supports IMAP and POP3. Odoo polls the mailbox on the configured schedule and routes each email to the appropriate record based on the subject's reply-to address or alias.
Common use: create helpdesk tickets or CRM leads from inbound email. Set the Create a New Record field to the target model.
Email Aliases#
An alias routes inbound email to a specific model and optionally a specific record. Go to Settings → Technical → Email → Aliases.
Example: support@yourcompany.odoo.com → creates a new Helpdesk ticket for each inbound email.
Alias Domain#
Set the alias domain in Settings → General Settings → Discuss → Alias Domain. This is the domain appended to alias addresses (e.g., @yourcompany.odoo.com).
For custom domains (e.g., support@yourdomain.com), configure your MX records to deliver mail to Odoo's mail server, then set the alias domain to your custom domain. Odoo.sh handles this automatically; on-premise requires MX record configuration with your DNS provider.
Mail Templates#
A mail template (mail.template) is a reusable email definition tied to a model. Templates use QWeb-style expressions to render field values from the record.
<record id="email_template_order_confirm" model="mail.template">
<field name="name">Sale Order: Confirmation</field>
<field name="model_id" ref="model_sale_order"/>
<field name="subject">Your order {{ object.name }} has been confirmed</field>
<field name="body_html">
<![CDATA[
<p>Dear {{ object.partner_id.name }},</p>
<p>Your order <strong>{{ object.name }}</strong> has been confirmed.</p>
]]>
</field>
<field name="email_to">{{ object.partner_id.email }}</field>
<field name="auto_delete" eval="True"/>
</record>Send a template from Python:
template = self.env.ref('my_module.email_template_order_confirm')
template.send_mail(self.id, force_send=True)Bounce Management#
When an email bounces (invalid address, full mailbox), Odoo's mail system can track the bounce and mark the partner's email address as invalid.
Set up bounce handling by configuring a dedicated bounce address (the bounce alias on your alias domain). Odoo parses DSN (Delivery Status Notification) bounce emails and links them to the original sent message.
In Settings → Technical → Email → Aliases, ensure a bounce alias exists pointing to the mail.bounce.alias model.
Four Deliverability Problems#
1. Emails go to spam due to missing SPF record#
Symptom: Recipients see your email in spam.
Cause: Your sending domain has no SPF record authorizing your SMTP server's IP.
Fix: Add a TXT record to your DNS: v=spf1 include:yoursmtpprovider.com ~all. If using Odoo.sh or Odoo Online, check their SPF requirements in the docs.
2. DKIM signature missing#
Symptom: Some receiving mail servers reject your email or mark it spam.
Cause: No DKIM private key configured for your sending domain.
Fix: Generate a DKIM key pair. Add the public key as a TXT DNS record. Configure your SMTP relay to sign outbound messages with the private key. Odoo itself does not sign DKIM - your relay must handle this.
3. Reply-to loop creates infinite threads#
Symptom: A user replies to a notification; Odoo receives the reply and creates another notification, which loops.
Cause: The reply-to address is an alias that triggers record creation, and the record creation sends another notification to the same address.
Fix: Check alias routing - ensure reply-to addresses on notification emails route to the correct record update handler, not a record creation alias.
4. Emails queued but never sent#
Symptom: Emails visible in Settings → Technical → Email → Emails with state "Outgoing" but never sent.
Cause: The mail queue cron job (ir.mail_server send queue) is paused, misconfigured, or the SMTP server is rejecting connections.
Fix: Check Settings → Technical → Automation → Scheduled Actions → "Send Email Queue". Confirm it is active and the last run succeeded. Check the Odoo server log for SMTP errors.
ERPeek can inspect which mail templates are defined in your custom modules, which models have alias routing configured, and whether your outgoing server is correctly assigned per company. See the contact page.