A ProcessWire module: Extends WireMail to bypass PHP mail and send email via SendGrids Web API.
To use this module you'll need a SendGrid account.
This module is considered beta. It should be safe for production but testing has been limited to ProcessWire master branch version >= 2.8.35 | PHP 7.3. Please report issues if you find them within Github.
- ProcessWire >= 2.8
WireMailSendGrid extends \ProcessWire\WireMail. To access its methods, as is the case with all WireMail Classes, you have 3 different methods to generate a new instance:
$m = $mail->new(); // option A
$m = wireMail(); // option B
$m = $modules->get('WireMailSendGrid'); // option C
Once you have a new mail() instance you can access the public set methods or directly communicate with \SendGrid\Mail\Mail() via the modules $email property, i.e.
$m = $mail->new();
// call a public method on the module
$m->setTemplateId(<template-id>);
// call a method directly on the \SendGrid\Mail\Mail() instance
$m->email->setClickTracking(<enable>, <enable-text>);
For further info on the methods available via \SendGrid\Mail\Mail() see:
https://github.com/sendgrid/sendgrid-php/
Module Config settings are applied globally, so every email sent via WireMailSendGrid will recieve the config you set. You can override the config per instance by calling the modules methods as above.
Use an existing, or log into SendGrid and under Settings generate a new API Key: SendGrid Settings / API Keys
Copy and Paste your API Key into this field.
As a minimum, the API Key requires Full Mail Send Permissions.
For further info on API Keys: SendGrid API Keys Docs
This is your default from email address. It is overwritten when a from address is passed to WireMail.
This is your default from email name. It is overwritten when a from name is passed to WireMail.
This is your default reply-to email address. It is overwritten when a reply-to address is passed to WireMail.
If not populated the emails from address is used for replies.
This is your default reply-to email address. It is overwritten when a reply-to address is passed to WireMail.
Allows you to track whether a recipient clicked a link in your email.
Enables click tracking globally.
Indicates if this setting should be included in the text/plain portion of your email.
Allows you to track whether the email was opened or not, by including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.
Enables open tracking globally.
Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel.
Allows you to insert a subscription management link at the bottom of the text and html bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag.
Enables subscription tracking globally.
Text to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>
HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>
A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the text and html parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting.
Allows you to enable tracking provided by Google Analytics.
Enables Google Analytics tracking globally.
Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email).
Name of the marketing medium. (e.g. Email).
Used to identify any paid keywords.
Used to differentiate your campaign from advertisements.
The name of the campaign.
This allows you to send a test email to ensure that your request body is valid and formatted correctly.
Useful for testing, will usually just pass a 202 code to the logs to indicate a mail was sent. Disable once set up as has little value in production.
Errors are always logged.
method: ___send()
Prevents the use of WireMail and Processes the email sending via SendGrids Web API.
method: to($email = '', $name = '', $substitutions = null, $subject = null)
args:
@param {string} $email - email address
@param {string} $name - name of the person associated with the email
@param {array|null} $substitutions - key/value substitutions to be be applied to an email template
@param {string|null} $subject - personalized subject of the email
@return $this
Sets an email 'to' payload. Emails can have multiple 'to' payloads via seperate calls to this method with distinct $email args.
method: toName($name = '', $email = '')
args:
@param {string} $name - name of the person associated with the email
@param {string} $email - email address
@return $this
method: cc($email = '', $name = '', $substitutions = null, $subject = null)
args:
@param {string} $email - email address
@param {string} $name - name of the person associated with the email
@param {array|null} $substitutions - key/value substitutions to be be applied to an email template
@param {string|null} $subject - personalized subject of the email
@return $this
Sets an email 'cc' payload. Emails can have multiple 'cc' payloads via seperate calls to this method with distinct $email args.
method: ccName($name = '', $email = '')
args:
@param {string} $name - name of the person associated with the email
@param {string} $email - email address
@return $this
method: bcc($email = '', $name = '', $substitutions = null, $subject = null)
args:
@param {string} $email - email address
@param {string} $name - name of the person associated with the email
@param {array|null} $substitutions - key/value substitutions to be be applied to an email template
@param {string|null} $subject - personalized subject of the email
@return $this
Sets an email 'bcc' payload. Emails can have multiple 'bcc' payloads via seperate calls to this method with distinct $email args.
method: bccName($name = '', $email = '')
args:
@param {string} $name - name of the person associated with the email
@param {string} $email - email address
@return $this
method: replyTo($email = '', $name = '')
args:
@param {string} $email - email address
@param {string} $name - name of the person associated with the email
@return $this
Sanitises and sets the emails reply-to address.
method: attachment($path = '', $filename = '', $disposition = null, $contentId = null)
args:
@param {string} $path - Full path and filename of file attachment
@param {string} $filename - Optional different basename for file as it appears in the mail
@param {string|null} $disposition - How the attachment should be displayed: inline or attachment
@param {string|null} $contentId - Used when disposition is inline to diplay the file within the body of the email
@return $this
Add Attachments - provides fallback for older versions and adds SendGrid type and id to payload.
method: setTemplateId($id = '')
args:
@param {string} $id - SendGrid template ID
@return $this
@throws WireException if ID not a string
Set a SendGrid Template ID to render the email within.
method: setDynamicTemplateData($name = '', $value = '')
args:
@param {String} $name - dynamicTemplateSubstitution name/key
@param {String|Array|Object|Boolean|Integer|null} $value - if null unset the key
@return $this
@throws WireException if name not a string
Set a SendGrid Dynamic Template Substitution. Allows dynamicTemplateSubstitutions to be unset by passing a null value.
method: setCustomArg($name = '', $value = '')
args:
@param {String} $name - Custom Arg name/key
@param {String|null} $value - if null unset the key
@return $this
@throws WireException if name not a string
Set a SendGrid Custom Arg. Allows customArgs to be unset by passing a null value.
method: setSection($name = '', $value = '')
args:
@param {String} $name - Section name/key
@param {String|null} $value - if null unset the key
@return $this
@throws WireException if name not a string
Set a SendGrid section. Allows sections to be unset by passing a null value.
method: addCategory($category = '')
args:
@param {String} $category - category name
@return $this
@throws WireException if category not a string
Add a SendGrid category.
method: setSendAt($sendAt)
args:
@param {int} $sendAt - unix timestamp, when you want your email to be delivered. (no more than 72hrs away)
@return $this
@throws WireException if $sendAt not an int
Set a SendGrid sendAt value.
method: setBatchId($batchId)
args:
@param {String} $batchId - SendGrid Batch ID
@return $this
@throws WireException if $batchId not a string
Add the a batch ID value - ID represents a batch of emails to be sent at the same time.
When instantiated this module provides an $email param allowing you to directly call the methods available to the SendGrid API.
$m = $mail->new();
// call a method directly on the \SendGrid\Mail\Mail() instance
$m->email->setClickTracking(<enable>, <enable-text>);
For further info on the methods available via \SendGrid\Mail\Mail() see: