, (*1)
silverstripe-sendgrid
A module to assist developers in sending template emails via SendGrid, (*2)
Requirements
- silverstripe/framework: ^4.0
Installation
composer require vulcandigital/silverstripe-sendgrid
Configuration
mysite/_config/sendgrid.yml:, (*3)
Vulcan\SendGrid\SendGrid:
api_key: 'REPLACE-WITH-YOUR-API-KEY'
Usage
$sendGrid = \Vulcan\SendGrid\SendGrid::create();
$sendGrid->setSubject("We have a sale for you!");
$sendGrid->setFrom('marketing@example.com');
$sendGrid->setFromName('My Site');
$sendGrid->setReplyTo('sales@example.com');
$sendGrid->addRecipient('reece@vulcandigital.co.nz', 'Reece Alexander', [
':salutation' => 'Mr',
':button_link' => 'https://example.com/store/offer?id=aASdGdjnklashewjk12321hjkasd213'
]);
$sendGrid->setBody("<p>We thought you'd like this awesome t-shirt!</p>");
$sendGrid->setTemplateId('your-template-id');
$sendGrid->addAttachment(Image::get()->first());
$sendGrid->send();
You can add as many recipients as you want., (*4)
Substitutions & Custom Arguments
Substitutions and custom arguments are practically the same thing, the only difference is that custom arguments are applied globally regardless of the recipient where substitutions are variable replacements that can differ per recipient., (*5)
Substitutions will always override any custom argument, (*6)
Substitutions
Substitutions are variables that can be replaced per recipient, (*7)
$sendGrid->addRecipient('john@doe.com', 'John Doe', [
':salutation' => 'Mr',
':first_name' => 'John',
':last_name' => 'Doe'
]);
$sendGrid->addRecipient('jane@doe.com', 'Jane Doe', [
':salutation' => 'Mrs',
':first_name' => 'Jane',
':last_name' => 'Doe'
]);
Custom Arguments
Custom arguments are applied globally across all recipients unless a substitution has overridden it, (*8)
$sendGrid->addCustomArg(':year', DBDatetime::now()->Year());
Attachments
You can add as many attachments as you want totalling up to 30 MB. The attachment must be a File object or a subclass of it such as itself or Image., (*9)
$file = Image::get()->first();
$sendGrid->addAttachment($file, $filename = null, $forcePublish = false);
or you can use an absolute path to a file instead:, (*10)
$sendgrid->addAttachment('/public_html/path/to/image.png'));
$sendgrid->addAttachment(Controller::join_links(Director::baseFolder(), '/path/to/image2.png'));
If you provide $filename, make sure you provide the correct extension as well to prevent any errors, (*11)
If the provided file is a File object and $forcePublish is set to true and the File you have provided has not been published, it will be forcibly published., (*12)
Scheduling
You can schedule emails to be sent at a later date:, (*13)
$sendGrid->setScheduleTo(DBDatetime::now()->getTimestamp() + 3600); // Schedule to send in 1 hour
Important: Ensure that you have specified your correct timezone in your SendGrid account's settings, otherwise this may have unexpected results., (*14)
Your database timezone should also match the timezone you have specified in your account. See Core Environment Variables for information on how to modify the timezone used by your database., (*15)
It is always advised when dealing with dates and times in SilverStripe to use the functionality it has provided you as shown in the example above., (*16)
Sandbox Mode
$sendGrid->setSandboxMode(true);
If everything is OK, $sendGrid->send() will return true otherwise an error will be thrown., (*17)
License
BSD-3-Clause - Vulcan Digital Ltd, (*18)
Wallogit.com
