Newer
Older
SendGrid Integration for Drupal
--------------------------------------------------------------------------------
This project is not affiliated with SendGrid, Inc.
Damien McKenna
committed
Use the issue tracker located
at [Drupal.org](https://www.drupal.org/sendgrid_integration)
for bug reports or questions about this module. If you want more info about
SendGrid services, contact [SendGrid](https://sendgrid.com).
This module uses a wrapper library for the SendGrid API. At the moment the
wrapper library is for V2 of the API. V3 upgrade is being developed.
FUNCTIONALITY
--------------------------------------------------------------------------------
This module overrides default email sending behaviour and sending emails through
SendGrid Transactional Email service instead. Emails are sent via a web service
and does not function like SMTP therefore there are certain caveats with other
Alex Laughnan
committed
email formatting modules. Read below for details.
Failures to send are re-queued for sending later. Queue of failed messages are
run on a 60 minute interval.
REQUIREMENTS
--------------------------------------------------------------------------------
Damien McKenna
committed
- [Mailsystem](https://www.drupal.org/project/mailsystem) - A module to create
an agnostic management layer for Mail. Very useful for controlling the mail
system on Drupal.
- [Key module](https://www.drupal.org/project/key) - []
- PHP dependencies for this module are loaded via Composer in Drupal 8.
INSTALLATION
--------------------------------------------------------------------------------
Before starting your installation, be aware that this module uses composer to
load dependencies. In Drupal 8, there are different ways to configure your site
Damien McKenna
committed
to
use [composer for contributed modules](https://www.drupal.org/node/2718229#managing-contributed).
As of recent changes with Drush for Drupal 8.4, there is no option to download
a module with Drush. All downloading of modules now resides with composer.
Damien McKenna
committed
## Installation via command line and composer
Damien McKenna
committed
- Start at the root of your Drupal installation and run this command:
Damien McKenna
committed
composer require drupal/sendgrid_integration
Damien McKenna
committed
The module will be downloaded from drupal.org, the dependency API wrapper will
be downloaded from Github, and the site's composer.json and composer.lock
files will be updated.
- Navigate to the "Extend" page in the Drupal UI and enable the "SendGrid
Integration" item in the "Mail" category.
Damien McKenna
committed
Composer
Documentation: [https://getcomposer.org/doc/](https://getcomposer.org/doc/)
Damien McKenna
committed
### Configuration without the Key module
Damien McKenna
committed
If the [Key module](https://www.drupal.org/project/key) is not installed,
perform the following steps:
Damien McKenna
committed
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
- Go to Configuration > System > Sendgrid Integration
(`admin/config/services/sendgrid`).
- Copy the API key value from the SendGrid dashboard to the "API Secret Key"
field on the form.
- Click "Save" to store the key.
Note: it is not currently possible to perform this simpler approach to
configuration if the Key module is installed, the steps below must be used.
#### Optional: manage the API key secure via settings.php
Modern security practices recommend storing API keys in a file that is not
stored in the code repository, to avoid anyone else using the key should they
gain unauthorized access to the repository. The use of the Key module makes this
a little more complicated.
In order to control the API key via settings.php it is first necessary to build
the configuration as described above so that it all works correctly. Once that
has been confirmed, make the following changes:
- Modify the settings.php file (or a file loaded by it) to add the following:
// SendGrid Integration: API key.
$config['sendgrid_integration.settings']['apikey'] = 'THEAPIKEY';
Replace "THEAPIKEY" with the API key provided by SendGrid.
- Modify the configuration in the UI to replace the stored API key with a
placeholder, e.g. `API-KEY-IS-IN-SETTINGS-FILE`.
- Try sending a test message from `admin/config/services/sendgrid/test` to
ensure it is still working.
- Presuming everything is still working correctly, export the site's
configuration and commit the changes to the key yml file, but not the
settings.php (or file loaded by settings.php).
### Configuration with the Key module
If the [Key module](https://www.drupal.org/project/key) is installed it will be
used for managing the API key; it is not currently possible to
Configure the site as follows:
- Create a key definition using the Key module:
- Load the Key module's settings page: `admin/config/system/keys`
- Click the "Add key" button.
- Fill in a name for this key, e.g. "SendGrid API key".
- Fill in a description for this key, if needed.
- For the "Key type" field select "Authentication".
- For the "Key provider" field select "Configuration".
- For the "Key value" field, paste in the API key provided by SendGrid.
- Click "Save".
- In the SendGrid settings (`admin/config/services/sendgrid`) on the "API-key"
field select the key created above.
- Confirm that the mail system is setup to use Sendgrid for how you wish to run
your website. If you want it all to run through Sendgrid then you set the
System-wide default MailSystemInterface class to "SendGridMailSystem". As an
example, see this image:
`https://www.drupal.org/files/issues/sengrid-integration-mailsystem-settings-example.png`
#### Optional: manage the API key secure via settings.php
Modern security practices recommend storing API keys in a file that is not
stored in the code repository, to avoid anyone else using the key should they
gain unauthorized access to the repository. The use of the Key module makes this
a little more complicated.
In order to control the API key via settings.php it is first necessary to build
the configuration as described above so that it all works correctly. Once that
has been confirmed, make the following changes:
- Modify the settings.php file (or a file loaded by it) to add the following:
// SendGrid Integration: API key.
$config['key.key.SENDGRIDKEYNAME']['key_provider_settings']['key_value'] = 'THEAPIKEY';
Replace "SENDGRIDKEYNAME" with the machine name of the key item created
earlier, and "THEAPIKEY" with the API key provided by SendGrid.
- Modify the configuration in the UI to replace the stored API key with a
placeholder, e.g. `API-KEY-IS-IN-SETTINGS-FILE`.
- Try sending a test message from `admin/config/services/sendgrid/test` to
ensure it is still working.
- Presuming everything is still working correctly, export the site's
configuration and commit the changes to the key yml file, but not the
settings.php (or file loaded by settings.php).
HTML Email
--------------------------------------------------------------------------------
In order to send HTML email. Your installation of Drupal must generate an email
with the proper headers.
Damien McKenna
committed
We recommend using the
module [Mimemail](https://www.drupal.org/project/mimemail)
for HTML formatting of emails.
Damien McKenna
committed
NOTE: Please note that SendGrid Integration also adds a "per module" setting
for\
the mail formatter/sender below where the site default is defined. The formatter
there needs to be changed to Mimemail.
OPTIONAL
--------------------------------------------------------------------------------
Alex Laughnan
committed
If sending email fails with certain (predefined) response codes the message be
added to Cron Queue for later delivery. In order for this to function, you must
configure Cron running period and when it is possible also add your drupal site
to crontab (Linux only), read more about cron at https://www.drupal.org/cron.
If you would like a record of the emails being sent by the website, installing
Maillog (https://www.drupal.org/project/maillog) will allow you to store local
copies of the emails sent. Sendgrid does not store the content of the email.
Damien McKenna
committed
DEBUGGING
--------------------------------------------------------------------------------
Debugging this module while installed can be done by installing the Maillog
module (https://www.drupal.org/project/maillog). This module will allow you to
store the emails locally before they are sent and view the message generated
in the Sendgrid email object.
RESOURCES
--------------------------------------------------------------------------------
Alex Laughnan
committed
Information about the Sendgrid PHP Library is available on Github:
https://github.com/taz77/sendgrid-php-ng