[IMP] email: add mail.default.from_filter

StraubCreative · StraubCreative · commit b5773fb61b58 · 2022-12-07T11:39:18.000-08:00
diff --git a/content/applications/general/email_communication/email_domain.rst b/content/applications/general/email_communication/email_domain.rst
@@ -1,163 +1,190 @@
-========================
-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*.
 
-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.
 
-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.
+Emails from the database users to partners (customers or vendors) are sent from the email addresses
+of the database users. Similarly, emails from partners to users are sent from the email addresses
+of the partners. That way, the database users can recognize who sent an email relayed by Odoo.
 
-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 from the database users reach the partners, 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 (gmail.com, outlook.com, etc.).
 
 .. _email_communication/spf_compliant:
 
 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
+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
+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) 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.
 
-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.
+There are three :abbr:`DMARC (Domain-based Message Authentication, Reporting, & Conformance)`
+policies:
 
-There are three DMARC policies:
-- ``p=none``
-- ``p=quarantine``
-- ``p=reject``
+- `p=none`
+- `p=quarantine`
+- `p=reject`
 
-``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=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 your domain name uses DMARC and has defined one of these policies, it is therefore imperative
-to be SPF compliant or to enable DKIM.
+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:
 
-SPF, DKIM & DMARC documentation of common providers
-===================================================
+SPF, DKIM, & DMARC documentation of common providers
+====================================================
 
 - `OVH DNS <https://docs.ovh.com/us/en/domains/web_hosting_how_to_edit_my_dns_zone/>`_
 - `OVH SPF <https://docs.ovh.com/us/en/domains/web_hosting_the_spf_record/>`_
 - `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.
+
+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:
+
+- `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 ``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>`_.
+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`.
 
-You access the **System Parameters** in :ref:`developer mode <developer-mode>` in the :menuselection:`Settings -->
-Technical --> Parameters --> System Parameters` menu.
+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`.
