Deliver Email Through Your Drupal Site on the Pantheon Platform
Detailed information on using SendGrid to deliver email through your Drupal site.
Discuss in our Forum Discuss in SlackEmail is a necessity when running a website - whether it's used with a simple contact form or to manage subscription based services. Email delivery can be used for notification of content updates, delivery of sales receipts, updates for password or membership information, and more. Email is the most effective way of communicating with a site's user base, and it is important that messages are filtered properly and not incorrectly marked as spam.
One of the most common reasons that an email gets blocked, is because it originates from a website hosted by a third party service, like Pantheon. To ensure this doesn't happen, Pantheon recommends using your own email server or a service provider such as SendGrid.
Note
A new Sendgrid account may need to wait 30 days before upgrading to a paid plan. If you're switching to Sendgrid from an existing email solution, make sure to plan for this.
Why SendGrid?
SendGrid has a lot of things going for it, all of which do the hard work for you when it comes to how mail is managed on your site. It can handle massive email campaigns while providing highly detailed and flexible reporting, along with the ability to scale and increase deliverability.
Create a SendGrid Account
Get started by signing up for an account and selecting a plan that meets your business needs. After receiving your confirmation email, sign in to your SendGrid account.
From within the Settings menu, click API Keys:
Click Create API Key to define the name and permissions for the API key your site will use. Click Create & View to complete the process.
The API key will only be displayed once. Copy the key and save it somewhere secure until you can apply it to the site.
From the Settings Menu, click Sender Authentication. SendGrid requires accounts created after April 6th 2020 to identify their sender identity through either Domain Authentication or Single Sender Verification. A more detailed explanation of these options can be found in the SendGrid documentation.
Integrating Sendgrid With Drupal
Follow the procedure outlined below for Drupal:
Choosing an Integration Method
Two methods can be used to integrate SendGrid with your Drupal site: API or SMTP.
Considerations
- SMTP requests are associated with dynamic outgoing IPs, which can have a negative impact on deliverability.
- API integration using the SendGrid Integration module is recommended; however, installation of this module is slightly more complicated, as it requires the use of Composer. For Drupal we can utilize the dev release of this module and use Composer in a non-invasive manner that is compatible with upstream updates.
API Integration
SendGrid API Integration
Exports
This process uses Terminus. Before we begin, set the variables $SITE and $ENV in your terminal session to match your site name and the Dev environment, or multidev name is using Multidev:
export SITE=yoursitename
export ENV=devInstall Composer and Drush, then install and authenticate Terminus.
If you haven't done so already, clone your Pantheon site repository and navigate to the project's root directory. If you're using Multidev, checkout that branch:
cd $SITE git checkout $ENVSet the connection mode to Git:
terminus connection:set $SITE.$ENV gitInstall the SendGrid Integration module (and its dependencies) and the Composer Vendor module using Drush:
drush dl sendgrid_integration-7.x-1.3 mailsystem composer_vendor
Start Composer
Now that the module and dependencies are installed, initialize Composer:
Initialize composer to create a
composer.jsonfile with the Drupal 7 package repository:composer init --repository=https://packages.drupal.org/7 --no-interactionEdit the
composer.jsonto add extra configuration that specifies installation paths for Drupal modules, libraries, and themes.Note
Since Pantheon does not support Git submodules , we recommend using the provided script
remove-git-submodulesto remove any.gitdirectories upon install and update.composer.json{ "repositories": [ { "type": "composer", "url": "https://packages.drupal.org/7" } ], "require": {}, "extra": { "installer-paths": { "sites/all/modules/{$name}/": ["type:drupal-module"], "sites/all/themes/{$name}/": ["type:drupal-theme"], "sites/all/libraries/{$name}/": ["type:drupal-library"] } }, "scripts": { "remove-git-submodules": "find . -mindepth 2 -type d -name .git | xargs rm -rf", "post-install-cmd": [ "@remove-git-submodules" ], "post-update-cmd": [ "@remove-git-submodules" ] }, "config": { "vendor-dir": "sites/all/vendor" } }
Protect Directory Path
The above configuration specifies setting vendor-dir to sites/all/vendor for compatibility with the Composer Vendor module, but this directory is not a protected path by default. Make this path non-web accessible by adding the following to the pantheon.yml configuration file:
protected_web_paths:
- /sites/all/vendorRequire the SendGrid API Library via Composer:
composer require fastglass/sendgrid:~1.0Add, commit, and push all of the new files:
git add . git commit -am "Add Sendgrid API Integration" git push origin master # or $ENV for multidevSwitch the site back to SFTP mode:
terminus connection:set $SITE.$ENV sftpEnable Composer Vendor, followed by SendGrid Integration. Order is important for this step. SendGrid Integration will refuse to activate if the library file is not autoloaded:
terminus drush $SITE.$ENV -- en composer_vendor -y terminus drush $SITE.$ENV -- en sendgrid_integration -yFrom within your SendGrid account, navigate to Settings > API Keys and create a site-specific API Key. Click the key to copy it to your keyboard.
Visit
/admin/config/services/sendgridonce you've logged into your Drupal site as an administrator. Paste your API Key and click Save Settings.
Your Drupal application on Pantheon is now set up to send email through SendGrid's API. Test your configuration from /admin/config/services/sendgrid/test.
Note
Under /admin/reports/status you may see a warning that composer.lock isn't found in code/sites/all. The actual composer.lock is in the code root, but you can symlink to it to remove the warning.
From the project root:
cd sites/all
ln -s ../../composer.lock ./composer.lockThen commit and push the symlink to Pantheon.
SMTP Integration
SendGrid SMTP Integration
Install the SMTP Authentication Support module using the Drupal interface or with Terminus:
terminus drush <site>.<env> -- en smtp -yVisit
/admin/config/system/smtponce you've logged in as the administrator.In Install Options, select On.
Use the following within SMTP Server Settings:
SMTP server:
smtp.sendgrid.netSMTP port:
2525Use encrypted protocol: We strongly recommend selecting TLS
Note
Configuring mail to use ports
25,465or587is strongly discouraged because it attracts spam activity. For details, see Email with Drupal on PantheonProvide your site-specific SendGrid credentials and click Save configuration. Note that subusers are not available on free plans.
Your Drupal application on Pantheon is now set up to send email through SendGrid. Provide an address within the Send Test E-mail configuration field and click Save configuration to test.
Checking Deliverability in SendGrid
For testing purposes, your first few deliveries should be to email addresses that you control directly. You can track and measure unique aspects of mail behaviors from within your site's SendGrid account, which should be monitored regularly.
First, log into SendGrid and select Activity. You will be taken to a page with a form to search by email. Enter the email address. SendGrid will search through your mail queue for any messages sent to that address. For additional search parameters, select the filters near the top right corner.
You can explore the Statistics and Email Reports from within your site's account to gain insight into email activity, statistics on email clients, and much more.
You have now successfully integrated an industrial strength, simple to use, email delivery service into your website. If you have any questions, contact SendGrid's support team or check SendGrid’s Email Infrastructure Guide for advanced tips on how to create and publish DNS records for increased deliverability.