Cloud Platform

Configuring Platform Email

Prerequisites

The following table lists the Platform Email configuration tasks and their prerequisites:

Step

Task

Prerequisites

1

Configuring a domain

Ensure that you have one of the following roles:

  • The organization’s owner

  • Administrator

2

Associating a domain to an application

Ensure that you have one of the following user roles:

  • Owner

  • Administrator

3

Configuring the email address for sending emails

An operational Drupal website hosted on Cloud Platform.

Methods for configuring Platform Email

The following are the methods for configuring Platform Email

Configuring Platform Email through the Cloud Platform user interface

Configuring a domain

Important

  • An email sending domain is a different entity than the website domain that you configure through the Domain Management page of your environment. Therefore, you must configure an email sending domain only through the Platform Email page. You must also configure the email sending domain and website domain on the DNS provider as two separate entities.

  • Platform Email allows configuration of a subdomain. However, it does not support configuration of a subdomain with the www prefix.

To configure and verify an email sending domain:

  1. Sign in to the Cloud Platform user interface and select the application for which you want to configure the domain.

  2. In the navigation pane, click Email.

  3. On the Platform Email page, on the Domain Verification tab, click ADD DOMAIN.

  4. In the Add domain dialog box, in the Domain to add field, enter the domain name that you want to configure, and click ADD DOMAIN.

    The Platform Email page displays the following message:

    The domain has been registered.

  5. In the Email domain verification list, verify that the new domain shows the Verification pending status.

    Note

    The domains listed in this section can be used on all applications that belong to the same subscription. You can also leverage the email:info command in Acquia CLI to get additional information. For example, if a domain is associated with multiple applications, this command lists all such applications and the association status. For more information, see Acquia CLI commands.

  6. Click the expand arrow for the domain to view the type, status, and value of the DNS records.

    The list of DNS records includes:

    • DKIM: Three entries of type CNAME

    • TXT: Two entries of type TXT

    • SPF: One entry of type TXT and one entry of type MX

    At this step, the status of the entries is Verification pending. For more information on the DNS records, see Adding DNS records for Platform Email.

  7. From the VALUE column of the list, copy all strings and add them to your DNS provider.

    Note

    • Copy each string carefully, ensuring that you don’t miss any letter.

    • When adding a domain to multiple subscriptions, verify the domain in one subscription first. Once the domain is verified in the first subscription, then add the domain to other subscriptions by adding and verifying one more TXT DNS record per subscription.

    For an MX record, a string consists of MX Priority and MX Value as shown in the following example:

    For an MX record, when you add a string to your DNS provider, ensure that you add MX Priority and MX Value based on the syntax of your DNS provider. For example, if your DNS provider has separate fields for priority and value, then add them separately. For information on how to add the MX records for different DNS providers, see Amazon SES documentation.

  8. Wait until the DNS records are verified.

    Verification of the DNS records may take up to 72 hours.

  9. On the Domain Verification tab, verify the status of the domain and do one of the following:

    • If the status is OK, associate the domain to the application.

    Important

    The DNS records must remain in your DNS for Platform Email to continue verifying your ownership of the domain. The following reminder message also appears under the OK status:

    Do not delete DNS entries for verified domains. Deleting DNS records at your DNS provider will revoke the verification.

    After configuring a domain for an application, you can associate the domain to any applications within your subscription.

Associating a domain to an application

To associate an email sending domain to an application:

  1. Sign in to the Cloud Platform user interface and select the application for which you configured the domain.

  2. In the navigation pane, click Email.

  3. On the Platform Email page, select the Domain Association tab.

  4. In the row for your domain, click Associate.

  5. In the Associate domain dialog box, click ASSOCIATE DOMAIN.

    On the Domain Association tab, the state of the domain changes to Associated.

Configuring the email address for sending emails

To configure the email address to be used for sending emails:

  1. Log on to your Drupal website.

  2. Select Configuration > Basic site settings > Site Details.

    Note

    The Basic site settings option is available to admin users. However, an admin can share the access with other Drupal app users.

  3. In the SITE DETAILS area, in the Email address field, enter the email address that must appear as the From address in the outgoing emails.

    Important

    This email address must have the same domain that is configured in the previous steps. If you use a different domain, the Platform Email service does not send any emails.

  4. Click Save configuration.

Configuring Platform Email through Acquia CLI

You can leverage Acquia CLI to get onboarded with Platform Email. Acquia recommends that you use this method to configure Platform Email for a large number of cloud applications.

Prerequisites

  • As a logged-in user, you must authenticate against your Cloud Platform account. For more information, see Authenticating with Cloud Platform API.

  • You must know:

    • The domain name that you want to register for Platform Email.

    • The subscription where you want to register the domain name.

    • The applications where you want to associate the domain.

    • The environments in the associated applications where you want to enable Platform Email.

To configure Platform Email through Acquia CLI:

  1. Access Acquia CLI.

  2. Run the following command to start the configuration process:

    acli email:configure

    The system displays the following output:

  3. In What’s the domain name you’d like to register, enter the name of your domain for which you want to enable Platform Email.

    For example, my-domain.com.

  4. Press Enter.

  5. In Please select a Cloud Platform subscription, enter the subscription ID associated with the subscription where you want to register the domain. The system displays all the subscriptions that are available for the logged-in user account.

    The system displays the following output:

  6. Press Enter.

  7. In Would you like your DNS records in JSON or YAML format, enter the ID associated with either JSON or YAML based on the format in which you want to view the DNS records.

    Based on your input, the system saves a text file in the directory where you run the Acquia CLI-based utility.

    A sample JSON text file:

    A sample YAML text file:

    Note

    This utility regenerates the text file each time the utility is run.

  8. Press Enter.

  9. In Have you finished providing the DNS records to your DNS provider, type yes or no.

    A sample output if your domain is already verified:

    If your domain is not yet verified, the system displays a pending notification. If your domain verification process fails, the system displays an error message and prompts the user to restart the verification process after checking the generated DNS record list with the records given to the DNS provider.

    Note

    If your subscription has multiple applications, the system displays all such applications and additionally prompts the user to select the applications where the domain will be associated. To associate the domain with multiple applications, you can enter comma-separated IDs.

  10. Press Enter.

  11. In What are the environments of <subscription_name> that you’d like email for?, enter the IDs specific to the environments for which you want to enable Platform Email.

    If your domain is associated with multiple applications, the system displays prompts for environments to be enabled for each of those applications. To enable Platform Email in multiple environments, you can enter comma-separated IDs.

    Platform Email is enabled for each of the specified environments.

Important

If you enabled Platform Email for a few environments and want to enable it for additional environments, you can run the preceding commands sequentially. The system displays a warning for the environments for which Platform Email is already enabled.

Adding DNS records for Platform Email

You must add DNS records in Platform Email. Platform Email supports the following types of DNS records:

  • SPF/MX records:

    Sender Policy Framework (SPF) is an email validation standard that is designed to prevent email spoofing. Domain owners use SPF to inform email providers about the servers that can send emails from their domains. To publish an SPF record, you must add a new TXT record to the DNS configuration for your domain. The procedures for updating DNS records vary depending on the DNS or web hosting provider you use.

    A mail exchanger record (MX record) is a configuration that specifies which mail servers can accept the email that is sent to your domain. To add an MX record, you must modify the DNS records for your domain. If you cannot access or modify the DNS records for your domain, contact your system administrator. For more information on MX records, see Why do I need an MX record for sending an email?.

  • DKIM records:

    DomainKeys Identified Mail (DKIM) standard allows senders to sign their email messages with a cryptographic key. Email providers use these signatures to verify that the messages weren’t modified by a third party while in transit. For more information, see Authenticating Email with DKIM in Amazon SES.

    Amazon SES requires you to add three DKIM records to enable Easy DKIM. When you set up Easy DKIM for an identity, Amazon SES automatically adds a 1024-bit DKIM key to every email that you send from that identity. These three records are part of the DKIM setup so that SES can rotate DKIM keys periodically. For more information, see Managing Easy DKIM and Easy DKIM in Amazon SES.

  • TXT records:

    TXT records contain text information for sources outside your domain. You add these records to your domain settings. Acquia uses them to verify domain ownership and to ensure email security. For more information, see Amazon SES domain verification TXT records.

Configuring modules for Platform Email

Configuring the mailsystem module

Platform Email is compatible with the Default PHP mailer module of Drupal.

Important

This module is not required for Platform Email.

If you have installed any custom module such as the mailsystem module, you must use Default PHP mailer as a sender.

To verify that you are using the Default PHP mailer module as sender:

  1. Access your Drupal site.

  2. Select Configuration > Mail System.

  3. Verify that the Sender field is set to Default PHP mailer.

  4. (Optional) For HTML support, set the Formatter field to Default PHP mailer.

    Note

    If you have not installed custom modules for emails, the system does not display the drop-down menu highlighted on the preceding screen.