diff --git a/content/applications/general/email_communication/email_domain.rst b/content/applications/general/email_communication/email_domain.rst index b00d4a651..5a7b15577 100644 --- a/content/applications/general/email_communication/email_domain.rst +++ b/content/applications/general/email_communication/email_domain.rst @@ -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 ` 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 ` 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 `. -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 `_. +Check if the :abbr:`SPF (Sender Policy Framework)` record is valid with a free tool like `MXToolbox +SPF `_. .. _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 `. -You can check if your DKIM record is valid with a free tool like -`DKIM Core `_. 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 `_. 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 `_. +Check the :abbr:`DMARC (Domain-based Message Authentication, Reporting, & Conformance)` record of a +domain name with a tool like `MXToolbox DMARC `_. -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 `, or replace the -email address of the partner with a default email address. +To solve this issue, :ref:`handle user notifications in Odoo +`, 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 `_ - `GoDaddy SPF `_ - `GoDaddy DKIM `_ -- `NameCheap `_ +- `NameCheap `_ - `CloudFlare DNS `_ - `Google Domains `_ - `Azure DNS `_ -To fully test your configuration, the tool `Mail-Tester `_ 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 `_ 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 ` 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 - `_. +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 ` 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`.