[ADD] maintain: setup mailjet api

closes odoo/documentation#3307

X-original-commit: 197a1cc932
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
Signed-off-by: Samuel Lieber (sali) <sali@odoo.com>

content/administration/maintain.rst

@@ -8,6 +8,7 @@ Maintain
 
     maintain/domain_names
     maintain/google_oauth
+    maintain/mailjet_api
     maintain/update
     maintain/enterprise
     maintain/hosting_changes

content/administration/maintain/mailjet_api.rst

@@ -0,0 +1,218 @@
+===========
+Mailjet API
+===========
+
+Odoo is compatible with Mailjet's :abbr:`API (Application Programming Interface)` for mass mailing.
+Set up a dedicated mass mailing server through Mailjet by configuring settings in the Mailjet
+account and the Odoo database. In some circumstances, settings need to be configured on the custom
+domain's :abbr:`DNS (Domain Name System)` settings as well.
+
+Set up in Mailjet
+=================
+
+Create API credentials
+----------------------
+
+To get started, sign in to the `Mailjet Account Information <https://app.mailjet.com/account>`_
+page. Next, navigate to the :guilabel:`Senders & Domains` section and click on :guilabel:`SMTP and
+SEND API Settings`.
+
+.. image:: mailjet_api/api-settings.png
+   :align: center
+   :alt: SMTP and Send API Settings link in the Senders & Domains section of Mailjet.
+
+Then, copy the :abbr:`SMTP (Simple Mail Transfer Protocol)` configuration settings onto a notepad.
+They can be found under the :guilabel:`Configuration (SMTP only)` section. The :abbr:`SMTP (Simple
+Mail Transfer Protocol)` configuration settings include the server address, the security option
+needed (Use :abbr:`SSL (Secure Sockets Layer)`/:abbr:`TLS (Transport Layer Security)`), and the
+port number. The settings are needed to configure Mailjet in Odoo, which is covered in the
+:ref:`last section <maintain/mailjet-api/odoo-setup>`.
+
+.. seealso::
+   `Mailjet: How can I configure my SMTP parameters?
+   <https://documentation.mailjet.com/hc/articles/360043229473>`_
+
+.. important::
+   Odoo blocks `port 25` on Odoo Online and Odoo.sh databases. :ref:`See reference here
+   <email_servers/restriction>`.
+
+.. image:: mailjet_api/smtp-config.png
+   :align: center
+   :alt: SMTP configuration from Mailjet.
+
+Next, click on the button labeled :guilabel:`Retrieve your API credentials` to retrieve the Mailjet
+API credentials.
+
+Then, click on the eye icon to reveal the :guilabel:`API key`. Copy this key to a notepad, as this
+serves as the :guilabel:`Username` in the Odoo configuration. Next, click on the
+:guilabel:`Generate Secret Key` button to generate the :guilabel:`Secret Key`. Copy this key to a
+notepad, as this serves as the :guilabel:`Password` in the Odoo configuration.
+
+Add verified sender address(es)
+-------------------------------
+
+The next step is to add a sender address or a domain to the Mailjet account settings so that the
+email address or domain is approved to send emails using Mailjet's servers. First, navigate to the
+`Mailjet Account Information <https://app.mailjet.com/account>`_ page. Next, click on the
+:guilabel:`Add a Sender Domain or Address` link under the :guilabel:`Senders & Domains` section.
+
+.. image:: mailjet_api/add-domain-email.png
+   :align: center
+   :alt: Add a sender domain or address in the Mailjet interface.
+
+Determine if a sender's email address or the entire domain needs to be added to the Mailjet
+settings. It may be easier to configure the domain as a whole if :abbr:`DNS (Domain Name System)`
+access is available. Jump to the :ref:`Add a domain <maintain/mailjet-api/add-domain>` section for
+steps on adding the domain.
+
+.. note::
+   Either all email addresses of the Odoo database users who are sending emails using Mailjet's
+   servers need to be configured or the domain(s) of the users' email addresses can be configured.
+
+By default, the email address originally set up in the Mailjet account is added as a trusted
+sender. To add another email address, click on the button labeled :guilabel:`Add a sender address`.
+Then, add the email address that is configured to send from the custom domain.
+
+At minimum the following email addresses should be set up in the provider and verified in Mailjet:
+
+- notifications\@yourdomain.com
+- bounce\@yourdomain.com
+- catchall\@yourdomain.com
+
+.. note::
+   Replace `yourdomain` with the custom domain for the Odoo database. If there isn't one, then use
+   the :guilabel:`mail.catchall.domain` system parameter.
+
+After that, fill out the :guilabel:`Email Information` form, making sure to select the appropriate
+email type: transactional email or mass emails. After completing the form, an activation email is
+sent to the email address and the trusted sender can be activated.
+
+It is recommended to set up the :abbr:`SPF (Sender Policy Framework)`/:abbr:`DKIM (DomainKeys
+Identified Mail)`/:abbr:`DMARC (Domain-based Message Authentication, Reporting, and
+Conformance)` settings on the domain of the sender.
+
+.. seealso::
+   `Mailjet's SPF/DKIM/DMARC documentation <https://documentation.mailjet.com/hc/articles/
+   360042412734-Authenticating-Domains-with-SPF-DKIM>`_
+
+.. important::
+   If the database is not using a custom domain, then in order to verify the sender's address, a
+   temporary alias (of the three email addresses mentioned above) should be set up in Odoo CRM to
+   create a lead. Then, the database is able to receive the verification email and verify the
+   accounts.
+
+.. _maintain/mailjet-api/add-domain:
+
+Add a domain
+------------
+
+By adding an entire domain to the Mailjet account, all the sender addresses related to that domain
+are automatically validated for sending emails using Mailjet servers. First, navigate to the
+`Mailjet Account Information <https://app.mailjet.com/account>`_ page. Next, click on
+:guilabel:`Add a Sender Domain or Address` link under the :guilabel:`Senders & Domains` section.
+Then, click on :guilabel:`Add domain` to add the custom domain.
+
+.. note::
+   The domain needs to be added to the Mailjet account and then validated through the :abbr:`DNS
+   (Domain Name System)`.
+
+After that, fill out the :guilabel:`Add a new Domain` page on Mailjet and click
+:guilabel:`Continue`.
+
+After adding the domain, a validation page will populate. Unless the Odoo database is on-premise
+(in which case, choose :guilabel:`Option 1`), choose :guilabel:`Option 2: Create a DNS Record`.
+Copy the TXT record information to a notepad and then navigate to the domain's :abbr:`DNS (Domain
+Name System)` provider to complete validation.
+
+.. image:: mailjet_api/host-value-dns.png
+   :align: center
+   :alt: The TXT record information to input on the domain's DNS.
+
+Setup in the domain's DNS
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After getting the TXT record information from the Mailjet account, add a TXT record to the domain's
+:abbr:`DNS (Domain Name System)`. This process varies depending on the :abbr:`DNS (Domain Name
+System)` provider. Consult the provider for specific configuration processes. The TXT record
+information consists of the :guilabel:`Host` and :guilabel:`Value`. Paste these into
+the corresponding fields in the TXT record.
+
+Return to Mailjet account information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After adding the TXT record to the domain's :abbr:`DNS (Domain Name System)`, navigate back to the
+Mailjet account. Then, navigate to :menuselection:`Account Information --> Add a Sender Domain or
+Address`, click the gear icon next to :guilabel:`Domain`, and select :guilabel:`Validate`.
+
+This action can also be done by going to the `Sender domains & addresses <https://app.mailjet.com/
+account/sender>`_ page on the Mailjet account information and clicking on :guilabel:`Manage`.
+
+Next, click :guilabel:`Check Now` to validate the TXT record that was added on the domain. A
+success screen will appear if the domain is configured correctly.
+
+.. image:: mailjet_api/check-dns.png
+   :align: center
+   :alt: Check DNS record in Mailjet.
+
+After successfully setting up the domain, there is an option to :guilabel:`Authenticate this domain
+(SPF/DKIM)`. This button populates :abbr:`SPF (Sender Policy Framework)` & :abbr:`DKIM (DomainKeys
+Identified Mail) records to input into the :abbr:`DNS (Domain Name System)` provider.
+
+.. seealso::
+   `Mailjet's SPF/DKIM/DMARC documentation <https://documentation.mailjet.com/hc/articles/
+   360042412734-Authenticating-Domains-with-SPF-DKIM>`_
+
+.. image:: mailjet_api/authenticate.png
+   :align: center
+   :alt: Authenticate the domain with SPF/DKIM records in Mailjet.
+
+.. _maintain/mailjet-api/odoo-setup:
+
+Set up in Odoo
+==============
+
+To complete the setup, navigate to the Odoo database and go to the :guilabel:`Settings`. With
+:ref:`developer-mode` turned on, go to the :menuselection:`Technical Menu --> Email --> Outgoing
+Mail Servers`. Then, create a new outgoing server configuration by clicking on the
+:guilabel:`Create` button.
+
+Next, input the `SMTP server` (in-v3.mailjet.com), `port number` (587 or 465), and `Security
+(SSL/TLS)` that was copied earlier from the Mailjet account. They can also be found `here
+<https://app.mailjet.com/account/setup>`_. It is recommended to use :abbr:`SSL (Secure Sockets
+Layer)`/:abbr:`TLS (Transport Layer Security)` even though Mailjet may not require it.
+
+For the :guilabel:`Username`, input the :guilabel:`API KEY`. For the :guilabel:`Password`, input
+the :guilabel:`SECRET KEY` that was copied from the Mailjet account to the notepad earlier. These
+settings can be found on :menuselection:`Mailjet -->  Account Settings --> SMTP and SEND API
+Settings`.
+
+Then, if the Mailjet server is used for mass emailing, set the :guilabel:`Priority` value higher
+than that of any transactional email server(s). Finally, save the settings and :guilabel:`Test the
+Connection`.
+
+.. image:: mailjet_api/server-settings.png
+   :align: center
+   :alt: Odoo outgoing email server settings.
+
+.. important::
+   In order for the notifications feature to work using Mailjet, there are three settings that need
+   to be set in Odoo.
+
+   #. The :guilabel:`From Filter` needs to be set on the server configuration. It is recommended
+      to set it as a domain and not a full email address. It should match the domain in the two
+      proceeding steps. More information can be referenced :ref:`here
+      <email_servers/outgoing-email-server>`.
+   #. The :guilabel:`mail.default.from` system parameter must have the value
+      `notifications\@yourdomain.com`.
+   #. The :guilabel:`mail.default.from_filter` system parameter must have the value
+      `yourdomain.com`. Replace `yourdomain` with the custom domain for the Odoo database. If there
+      isn't one, then use the :guilabel:`mail.catchall.domain` system parameter.
+
+   For more information see :ref:`Using a default email address <email_domain/default>`.
+
+   The :guilabel:`System Parameters` can be accessed by activating
+   :doc:`../../applications/general/developer_mode` in the :menuselection:`Settings --> Technical
+   --> Parameters --> System Parameters` menu.
+
+Once the setup is complete, the Odoo database is ready to use the Mailjet email server for mass
+mailing or transactional emails!

content/applications/general/email_communication/email_domain.rst

@@ -167,6 +167,8 @@ To fully test the configuration, use the `Mail-Tester <https://www.mail-tester.c
 gives a full overview of the content and configuration in one sent email. Mail-Tester can also be
 used for other, lesser-known providers.
 
+.. _email_domain/default:
+
 Use a default email address
 ===========================
 

content/applications/general/email_communication/email_servers.rst

@@ -78,6 +78,8 @@ A G Suite server can be used for any Odoo hosting type. To do so, set up the SMT
 The configuration steps are explained in `Google documentation <https://support.google.com
 /a/answer/2956491?hl=en>`__.
 
+.. _email_servers/restriction:
+
 Restriction
 -----------
 
@@ -187,6 +189,8 @@ By default, inbound messages are fetched every 5 minutes in Odoo on-premise.
    :menuselection:`Settings --> Technical --> Automation --> Scheduled Actions` and look for
    :guilabel:`Mail: Fetchmail Service`.
 
+.. _email_servers/outgoing-email-server:
+
 Utilizing the From Filter on an outgoing email server
 =====================================================