Skip to content

Latest commit

 

History

History
254 lines (159 loc) · 12.7 KB

sendgrid.md

File metadata and controls

254 lines (159 loc) · 12.7 KB
Raw
title description tags categories type permalink contributors date
Using SendGrid To Deliver Email
Detailed information on using SendGrid to deliver email through your WordPress and Drupal site.
siteintegrations
moreguides
integrate
guide
docs/guides/:basename/
erikmathy
rvtraveller
wbconnor
sarahg
9/8/2015

Email is a necessity when running a website, whether it's used with a simple contact form or to manage subscription based services, odds are you’re going to need it. Users may want to receive notices of content updates, have sales receipts sent to them, update their password or membership information, and more. Email is the most effective way of communicating with a site's user base, but it does no good if these messages are filtered and marked as spam.

One of the most common reasons that email gets blocked is because it originates from a website hosted by a third party service, like Pantheon. In order to ensure this doesn't happen to you, we at Pantheon highly encourage using your own email server or a service provider such as SendGrid.

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

  1. 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.

  2. From within the Settings menu, click API Keys:

SendGrid Multiple User setup

  1. 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.

  2. The API key will only be displayed once. Copy the key and save it somewhere secure until you can apply it to the site.

Integrating Sendgrid With Drupal and WordPress

Follow the procedure outlined below for your CMS:

Download the WordPress SendGrid Plugin

The official SendGrid Plugin replaces the wp_mail function with API integration, making it easy to configure and get started.

Install and activate the latest release through the WordPress dashboard or place it in the code/wp-content/plugins directory and activate via the dashboard.

Add Your SendGrid Account Details

  1. After you have installed and activated the plugin, go to your site's Dashboard and select Settings, then click the SendGrid menu item.
  2. Provide the API Key from the previous section.
  3. Enter the email address to send from and provide a reply email address if you prefer replies to go to another address (optional).
  4. SendGrid supports categories so you can track email analytics and organize message types. Include any categories you would like to use, separated by commas.

WP Settings example

When you're done, click Update Setings. Your WordPress application is now set up to send email through SendGrid! Complete the fields in the SendGrid Test section of the Settings page and watch the magic work its way to your inbox. For guidance on checking deliverability in SendGrid, see Checking Deliverability in SendGrid.

Choosing an Integration Method

Two methods can be used to integrate SendGrid with your Drupal 8 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.

SendGrid API Integration

The SendGrid API Integration Module for Drupal 8 requires a Composer managed workflow as described in our Build Tools or Drupal 8 and Composer on Pantheon Without Continuous Integration guides. We cannot support non-Composer workflows using this module. For details, see the module readme file.

  1. Install the SendGrid Integration module using Composer:
composer require drupal/sendgrid_integration

  1. Commit, push, and enable the new module.

  2. Visit /admin/config/services/sendgrid once you've logged into your Drupal site as an administrator. Paste your API Key and click Save Configuration.

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.

SendGrid SMTP Integration

A stable release for Drupal 8 is not yet available for the SMTP Authentication Support module. However, some users have reported success with the beta version.

  1. Install the SMTP Authentication Support module using the Drupal interface or with Terminus:
terminus drush <site>.<env> -- en smtp -y
  1. Visit /admin/config/system/smtp once you've logged in as an administrator.
  2. From within Install Options, select On.
  3. Use the following within SMTP Server Settings:

SMTP server: smtp.sendgrid.net

SMTP port: 2525

Use encrypted protocol: We strongly recommend selecting TLS

<Alert title="Note" type="info">
Configuring mail to use port 25, 465 or 587 is strongly discouraged because these ports attract SPAM activities. For details, see [Email on Pantheon](/email)
</Alert>
  1. Provide your site-specific SendGrid credentials and click Save configuration.

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.

Choosing an Integration Method

Two methods can be used to integrate SendGrid with your Drupal 7 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 7 we can utilize the dev release of this module and use Composer in a non-invasive manner that is compatible with upstream updates.

SendGrid API Integration

  1. Install Composer, then install and authenticate Terminus.

  2. If you haven't done so already, clone your Pantheon site repository and navigate to the project's root directory. Replace <site_name> with your site's name (e.g., your-awesome-site):

export SITE=<site_name>
terminus connection:info $SITE.dev --fields='Git Command' --format=string
cd $SITE
  1. Set the connection mode to Git:
terminus connection:set $SITE.dev git
  1. Install the dev release of 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

Now that the module and dependencies are installed, initialize Composer:

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 before proceeding:

protected_web_paths:
  - /sites/all/vendor

  1. Require the SendGrid API Library via Composer:

    composer require fastglass/sendgrid:~1.0

  2. Add, commit, and push all of the new files:

git add .
git commit -am "Add Sendgrid API Integration"
git push origin master
  1. Switch the site back to SFTP mode:
terminus connection:set $SITE.dev sftp
  1. Enable Composer Vendor, followed by SendGrid Integration. Order is important here, 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 -y

  1. From 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.

  2. Visit /admin/config/services/sendgrid once you've logged into your Drupal site as 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.

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.lock

Then commit and push the symlink to Pantheon.

SendGrid SMTP Integration

  1. Install the SMTP Authentication Support module using the Drupal interface or with Terminus:

    terminus drush <site>.<env> -- en smtp -y

  2. Visit /admin/config/system/smtp once you've logged in as administrator.

  3. From within Install Options, select On.

  4. Use the following within SMTP Server Settings:

    SMTP server: smtp.sendgrid.net

    SMTP port: 2525

    Use encrypted protocol: We strongly recommend selecting TLS

    <Alert title="Note" type="info">

Configuring mail to use port 25, 465 or 587 is strongly discouraged because they attract SPAM activities. For details, see [Email on Pantheon](/email)

</Alert>

  5. Provide your site-specific SendGrid credentials and click Save configuration.

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, and press Enter. 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.

SendGrid email search options​

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.

Congratulations!

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 out SendGrid’s Email Infrastructure Guide for advanced tips on how to create and publish DNS records for increased deliverability.

Troubleshooting

In some cases, other WordPress plugins can conflict with the Sendgrid plugin and cause it to use PHPMailer instead of SendGrid.

See Also