[IMP] email: add mail.default.from_filter
closes odoo/documentation#2694 Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>
This commit is contained in:
Zachary Straub (ZST)
Sam Lieber (sali)
parent
3337ffa6c7
commit
df041b1212
@ -1,36 +1,37 @@
|
||||
========================
|
||||
Sending emails with Odoo
|
||||
========================
|
||||
=======================
|
||||
Send an email with Odoo
|
||||
=======================
|
||||
|
||||
Using your email domain in Odoo
|
||||
===============================
|
||||
Use an email domain in Odoo
|
||||
===========================
|
||||
|
||||
Documents in Odoo (a CRM opportunity, a sales order, an invoice ...) have a discussion thread,
|
||||
called *chatter*.
|
||||
Documents in Odoo (such as a CRM opportunity, a sales order, an invoice, etc.) have a discussion
|
||||
thread, called *chatter*.
|
||||
|
||||
When you post a message in the chatter, this message is sent by email to the followers of the
|
||||
document. If a follower replies to the message, the reply updates the chatter, and Odoo relays the
|
||||
reply to the followers.
|
||||
When a database user posts a message in the chatter, this message is sent by email to the followers
|
||||
of the document. If a follower replies to the message, the reply updates the chatter, and Odoo
|
||||
relays the reply to the followers as a notification.
|
||||
|
||||
Emails from your users to partners (customers, vendors) are sent from the email address of your
|
||||
users. Similarly, emails from partners to users are sent from the email address of the partners.
|
||||
This allows you to recognize at a glance who sent an email relayed by Odoo.
|
||||
Messages sent in the chatter from internal database users to external users (such as partners,
|
||||
customers, or vendors) are relayed on behalf of the database users. Messages sent back to the
|
||||
chatter from external users will appear in the chatter from their respective email addresses, or as
|
||||
they are listed in their Contacts record.
|
||||
|
||||
If your database is hosted on our cloud (Odoo Online or Odoo.sh), it is not necessary to add an
|
||||
outgoing email server to send emails from your custom domain. You can enjoy this feature by using
|
||||
the default Odoo email server.
|
||||
If the Odoo database is hosted on the cloud (Odoo Online or Odoo.sh), it is not necessary to add an
|
||||
outgoing email server to send emails from a custom domain.
|
||||
|
||||
.. important::
|
||||
The Odoo server is subject to a daily email limit to prevent abuse. The default limit is 200
|
||||
emails sent per day for databases with an Enterprise subscription. This limit can be increased
|
||||
under certain conditions. See our :doc:`FAQ <faq>` or contact support for more
|
||||
emails sent per day for databases with an **Enterprise** subscription. This limit can be
|
||||
increased under certain conditions. See the :doc:`FAQ <faq>` or contact support for more
|
||||
information.
|
||||
|
||||
However, it is recommended that you configure your domain name to ensure that emails from your
|
||||
users reach your partners, rather than being considered spam.
|
||||
To ensure that emails sent to and from the chatter reach their intended contacts, instead of being
|
||||
considered spam, Odoo recommends configuring the domain name.
|
||||
|
||||
For the same reason, we recommend that you always give your users an email address from a domain
|
||||
you manage, rather than a generic email address (gmail.com, outlook.com, etc.).
|
||||
For the same reason, Odoo also recommends giving each database user an email address from the
|
||||
configured domain, rather than a generic email address domain (such as gmail.com, outlook.com,
|
||||
etc.).
|
||||
|
||||
.. _email_communication/spf_compliant:
|
||||
|
||||
@ -38,97 +39,113 @@ Be SPF compliant
|
||||
================
|
||||
|
||||
The Sender Policy Framework (SPF) protocol allows the owner of a domain name to specify which
|
||||
servers are allowed to send email from that domain. When a server receives an incoming email,
|
||||
it checks whether the IP address of the sending server is on the list of allowed IPs according
|
||||
to the SPF record of the sender.
|
||||
servers are allowed to send emails from that domain. When a server receives an incoming email,
|
||||
it checks if the IP address of the sending server is on the list of allowed IPs according to the
|
||||
sender's :abbr:`SPF (Sender Policy Framework)` record.
|
||||
|
||||
.. note::
|
||||
The SPF verification is performed on the domain mentioned in the Return-Path field of the email.
|
||||
In the case of an email sent by Odoo, this domain corresponds to the value of the
|
||||
`mail.catchall.domain` key in the database system parameters.
|
||||
The :abbr:`SPF (Sender Policy Framework)` verification is performed on the domain mentioned in
|
||||
the `Return-Path` field of the email. In the case of an email sent by Odoo, this domain
|
||||
corresponds to the value of the `mail.catchall.domain` key in the database system parameters.
|
||||
|
||||
See the :ref:`documentation on incoming emails <email_communication/inbound_messages>`.
|
||||
|
||||
The SPF policy of a domain is set using a TXT record. How to create or modify a TXT record depends
|
||||
on the provider hosting the DNS zone of your domain name. In order for the verification to work
|
||||
properly, each domain can only have one SPF record.
|
||||
The :abbr:`SPF (Sender Policy Framework)` policy of a domain is set using a TXT record. The way to
|
||||
create or modify a TXT record depends on the provider hosting the :abbr:`DNS (Domain Name System)`
|
||||
zone of the domain name. In order for the verification to work properly, each domain can only have
|
||||
one :abbr:`SPF (Sender Policy Framework)` record.
|
||||
|
||||
If your domain name does not yet have an SPF record, the content of the record to create is as
|
||||
follows:
|
||||
If the domain name does not yet have an :abbr:`SPF (Sender Policy Framework)` record, the content
|
||||
of the record to create it is as follows:
|
||||
|
||||
``v=spf1 include:_spf.odoo.com ~all``
|
||||
`v=spf1 include:_spf.odoo.com ~all`
|
||||
|
||||
If your domain name already has an SPF record, you need to update this record (and do not create a
|
||||
new one).
|
||||
If the domain name already has an :abbr:`SPF (Sender Policy Framework)` record, the record must be
|
||||
updated (and do not create a new one).
|
||||
|
||||
.. example::
|
||||
|
||||
If your TXT record is `v=spf1 include:_spf.google.com ~all`, you need to edit it to add
|
||||
If the TXT record is `v=spf1 include:_spf.google.com ~all`, edit it to add
|
||||
`include:_spf.odoo.com`: `v=spf1 include:_spf.odoo.com include:_spf.google.com ~all`
|
||||
|
||||
You can check if your SPF record is valid with a free tool like
|
||||
`MXToolbox SPF <https://mxtoolbox.com/spf.aspx>`_.
|
||||
Check if the :abbr:`SPF (Sender Policy Framework)` record is valid with a free tool like `MXToolbox
|
||||
SPF <https://mxtoolbox.com/spf.aspx>`_.
|
||||
|
||||
.. _email_communication/DKIM_compliant:
|
||||
|
||||
Enable DKIM
|
||||
===========
|
||||
|
||||
The DomainKeys Identified Mail (DKIM) allows you to authenticate your emails with a digital signature.
|
||||
The DomainKeys Identified Mail (DKIM) allows a user to authenticate emails with a digital
|
||||
signature.
|
||||
|
||||
When sending an email, the Odoo server includes a unique DKIM signature in the headers. The
|
||||
recipient's server decrypts this signature using the DKIM record in your domain name. If the
|
||||
signature and the key contained in the record match, this guarantees that your message is authentic
|
||||
and has not been altered during transport.
|
||||
When sending an email, the Odoo server includes a unique :abbr:`DKIM (DomainKeys Identified Mail)`
|
||||
signature in the headers. The recipient's server decrypts this signature using the :abbr:`DKIM
|
||||
(DomainKeys Identified Mail)` record in the database's domain name. If the signature and the key
|
||||
contained in the record match, this guarantees that the message is authentic and has not been
|
||||
altered during transport.
|
||||
|
||||
To enable DKIM, you must add a CNAME record to the DNS zone of your domain name:
|
||||
To enable :abbr:`DKIM (DomainKeys Identified Mail)`, add a :abbr:`CNAME (Canonical Name)` record to
|
||||
the :abbr:`DNS (Domain Name System)` zone of the domain name:
|
||||
|
||||
``odoo._domainkey IN CNAME odoo._domainkey.odoo.com.``
|
||||
`odoo._domainkey IN CNAME odoo._domainkey.odoo.com.`
|
||||
|
||||
.. tip::
|
||||
If your domain name is `mycompany.com`, you need to create a subdomain
|
||||
If the domain name is `mycompany.com`, make sure to create a subdomain
|
||||
`odoo._domainkey.mycompany.com` whose canonical name is `odoo._domainkey.odoo.com.`.
|
||||
|
||||
How to create or modify a CNAME record depends on the provider hosting the DNS zone of your domain
|
||||
name. The most common providers are list below.
|
||||
The way to create or modify a :abbr:`CNAME (Canonical Name)` record depends on the provider hosting
|
||||
the :abbr:`DNS (Domain Name System)` zone of the domain name. The most common providers are
|
||||
:ref:`listed below <email_communication/SPFDKIM_common_providers>`.
|
||||
|
||||
You can check if your DKIM record is valid with a free tool like
|
||||
`DKIM Core <https://dkimcore.org/tools/>`_. If a selector is asked, enter `odoo`.
|
||||
Check if the :abbr:`DKIM (DomainKeys Identified Mail)` record is valid with a free tool like `DKIM
|
||||
Core <https://dkimcore.org/tools/>`_. If a selector is asked, enter `odoo`.
|
||||
|
||||
Check your DMARC policy
|
||||
=======================
|
||||
Check the DMARC policy
|
||||
======================
|
||||
|
||||
The Domain-based Message Authentication, Reporting & Conformance (DMARC) is a protocol that unifies SPF
|
||||
and DKIM. The instructions contained in the DMARC record of a domain name tell the destination
|
||||
server what to do with an incoming email that fails the SPF and/or DKIM check.
|
||||
The Domain-based Message Authentication, Reporting, & Conformance (DMARC) record is a protocol that
|
||||
unifies :abbr:`SPF (Sender Policy Framework)` and :abbr:`DKIM (DomainKeys Identified Mail)`. The
|
||||
instructions contained in the :abbr:`DMARC (Domain-based Message Authentication, Reporting, &
|
||||
Conformance)` record of a domain name tell the destination server what to do with an incoming email
|
||||
that fails the :abbr:`SPF (Sender Policy Framework)` and/or :abbr:`DKIM (DomainKeys Identified
|
||||
Mail)` check.
|
||||
|
||||
There are three DMARC policies:
|
||||
- ``p=none``
|
||||
- ``p=quarantine``
|
||||
- ``p=reject``
|
||||
There are three :abbr:`DMARC (Domain-based Message Authentication, Reporting, & Conformance)`
|
||||
policies:
|
||||
|
||||
``p=quarantine`` and ``p=reject`` instruct the server that receives an email to quarantine that
|
||||
email or ignore it if the SPF and/or DKIM check fails.
|
||||
- `p=none`
|
||||
- `p=quarantine`
|
||||
- `p=reject`
|
||||
|
||||
If your domain name uses DMARC and has defined one of these policies, it is therefore imperative
|
||||
to be SPF compliant or to enable DKIM.
|
||||
`p=quarantine` and `p=reject` instruct the server that receives an email to quarantine that email
|
||||
or ignore it if the :abbr:`SPF (Sender Policy Framework)` and/or :abbr:`DKIM (DomainKeys Identified
|
||||
Mail)` check fails.
|
||||
|
||||
If the domain name uses :abbr:`DMARC (Domain-based Message Authentication, Reporting, &
|
||||
Conformance)` and has defined one of these policies, the domain must be :abbr:`SPF (Sender Policy
|
||||
Framework)` compliant or enable :abbr:`DKIM (DomainKeys Identified Mail)`.
|
||||
|
||||
.. danger::
|
||||
Yahoo or AOL are examples of email providers with a DMARC policy set to ``p=reject``. We
|
||||
strongly advise against using an *@yahoo.com* or *@aol.com* address for your users. These emails
|
||||
will never reach their recipient.
|
||||
Yahoo or AOL are examples of email providers with a :abbr:`DMARC (Domain-based Message
|
||||
Authentication, Reporting, & Conformance)` policy set to `p=reject`. Odoo strongly advises
|
||||
against using an *@yahoo.com* or *@aol.com* address for the database users. These emails will
|
||||
never reach their recipient.
|
||||
|
||||
``p=none`` is used for the domain owner to receive reports about entities using their domain. It
|
||||
should not impact the deliverability if the DMARC check fails.
|
||||
`p=none` is used for the domain owner to receive reports about entities using their domain. It
|
||||
should not impact the deliverability if the :abbr:`DMARC (Domain-based Message Authentication,
|
||||
Reporting, & Conformance)` check fails.
|
||||
|
||||
You can check the DMARC record of a domain name with a tool like
|
||||
`MXToolbox DMARC <https://mxtoolbox.com/DMARC.aspx>`_.
|
||||
Check the :abbr:`DMARC (Domain-based Message Authentication, Reporting, & Conformance)` record of a
|
||||
domain name with a tool like `MXToolbox DMARC <https://mxtoolbox.com/DMARC.aspx>`_.
|
||||
|
||||
If one of your partners, customer or vendor, uses DMARC and has defined one of these policies, the
|
||||
Odoo server cannot relay emails from this partner to your users.
|
||||
If a partner, customer, or vendor, uses :abbr:`DMARC (Domain-based Message Authentication,
|
||||
Reporting, & Conformance)` and has defined one of these policies, the Odoo server cannot relay
|
||||
emails from this partner to the database users.
|
||||
|
||||
You need to :ref:`handle user notifications in Odoo <discuss_app/notification_preferences>`, or replace the
|
||||
email address of the partner with a default email address.
|
||||
To solve this issue, :ref:`handle user notifications in Odoo
|
||||
<discuss_app/notification_preferences>`, or replace the email address of the partner with a default
|
||||
email address.
|
||||
|
||||
.. _email_communication/SPFDKIM_common_providers:
|
||||
|
||||
@ -140,24 +157,36 @@ SPF, DKIM & DMARC documentation of common providers
|
||||
- `GoDaddy TXT record <https://www.godaddy.com/help/add-a-txt-record-19232>`_
|
||||
- `GoDaddy SPF <https://www.godaddy.com/help/add-an-spf-record-19218>`_
|
||||
- `GoDaddy DKIM <https://www.godaddy.com/help/add-a-cname-record-19236>`_
|
||||
- `NameCheap <https://www.namecheap.com/support/knowledgebase/article.aspx/317/2237/how-do-i-add-txtspfdkimdmarc-records-for-my-domain/>`_
|
||||
- `NameCheap <https://www.namecheap.com/support/knowledgebase/article.aspx/317/2237/how-do-i-add-
|
||||
txtspfdkimdmarc-records-for-my-domain/>`_
|
||||
- `CloudFlare DNS <https://support.cloudflare.com/hc/en-us/articles/360019093151>`_
|
||||
- `Google Domains <https://support.google.com/domains/answer/3290350?hl=en>`_
|
||||
- `Azure DNS <https://docs.microsoft.com/en-us/azure/dns/dns-getstarted-portal>`_
|
||||
|
||||
To fully test your configuration, the tool `Mail-Tester <https://www.mail-tester.com/>`_ will give
|
||||
you a full overview of the content and configuration you have in one email sent! Mail-Tester can
|
||||
also be used for other lesser known providers.
|
||||
To fully test the configuration, use the `Mail-Tester <https://www.mail-tester.com/>`_ tool, which
|
||||
gives a full overview of the content and configuration in one sent email. Mail-Tester can also be
|
||||
used for other, lesser-known providers.
|
||||
|
||||
Use a default email address
|
||||
===========================
|
||||
|
||||
To force the email address from which emails are sent, you need to create the following key in
|
||||
the System Parameters of the database:
|
||||
Access the :guilabel:`System Parameters` by activating :ref:`developer mode <developer-mode>` and
|
||||
going to :menuselection:`Settings --> Technical --> Parameters --> System Parameters` menu.
|
||||
|
||||
- If ``mail.default.from`` is set, and contains a full email address, all outgoing emails are sent
|
||||
from the given address. This is a requirement to use `Outlook with Odoo
|
||||
<https://docs.microsoft.com/en-us/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365#option-1-authenticate-your-device-or-application-directly-with-a-microsoft-365-or-office-365-mailbox-and-send-mail-using-smtp-auth-client-submission>`_.
|
||||
To force the email address from which emails are sent, a combination of the following keys needs to
|
||||
be set in the system parameters of the database:
|
||||
|
||||
You access the **System Parameters** in :ref:`developer mode <developer-mode>` in the :menuselection:`Settings -->
|
||||
Technical --> Parameters --> System Parameters` menu.
|
||||
- `mail.default.from`: accepts the local part or a complete email address as value
|
||||
- `mail.default.from_filter`: accepts a domain name or a full email address as value
|
||||
|
||||
.. note::
|
||||
The `mail.default.from_filter` works only for `odoo-bin` configurations, otherwise this
|
||||
parameter can be set using the `from_filter` field on `ir.mail_server`.
|
||||
|
||||
If the email address of the author does not match `mail.default.from_filter`, the email address is
|
||||
replaced by `mail.default.from` (if it contains a full email address) or a combination of
|
||||
`mail.default.from` and `mail.catchall.domain`.
|
||||
|
||||
If the `from_filter` contains a full email address, and if the `mail.default.from` is the same as
|
||||
this address, then all of the email addresses that are different from `mail.default.from` will be
|
||||
encapsulated in `mail.default.from`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user