sendgrid.cfc

A CFML wrapper for the SendGrid's Web API v3. It currently supports building and sending transactional emails, as well as portions of the API related to marketing emails.

Acknowledgements

This project borrows heavily from the API frameworks built by jcberquist. Thanks to John for all the inspiration!

Table of Contents

• Installation
  • Standalone Usage
  • Use as a ColdBox Module
• Quick Start for Sending
• Setup and Authentication
  • A Note on Email Validation
• How to build an email
• sendgrid.cfc Reference Manual
• Reference Manual for helpers.mail
• Reference Manual for helpers.campaign
• Reference Manual for helpers.sender
• Reference Manual for helpers.domain
• Reference Manual for helpers.webhook
• Questions
• Contributing

Installation

This wrapper can be installed as standalone component or as a ColdBox Module. Either approach requires a simple CommandBox command:

box install sendgridcfc

If you can't use CommandBox, all you need to use this wrapper as a standalone component is the sendgrid.cfc file and the helper components, located in /helpers; add them to your application wherever you store cfcs. But you should really be using CommandBox.

Standalone Usage

This component will be installed into a directory called sendgridcfc in whichever directory you have chosen and can then be instantiated directly like so:

sendgrid = new sendgridcfc.sendgrid( apiKey = 'xxx' );

Note that this wrapper was not designed to be placed within the shared CustomTags directory. If implemented as a CustomTag, it will conflict with the older mail() function syntax, as discussed in this issue.

Use as a ColdBox Module

To use the wrapper as a ColdBox Module you will need to pass the configuration settings in from your config/Coldbox.cfc. This is done within the moduleSettings struct:

moduleSettings = {
  sendgridcfc = {
    apiKey = 'xxx'
  }
};

You can then leverage the CFC via the injection DSL: sendgrid@sendgridcfc; the helper components follow the same pattern:

property name="sendgrid" inject="sendgrid@sendgridcfc";
property name="mail" inject="mail@sendgridcfc";
property name="campaign" inject="campaign@sendgridcfc";
property name="sender" inject="sender@sendgridcfc";
property name="domain" inject="domain@sendgridcfc";
property name="webhook" inject="webhook@sendgridcfc";

Quick Start

The following is a minimal example of sending an email, using the mail helper object.

sg = new path.to.sendgridcfc.sendgrid( apiKey = 'xxx' );

mail = new path.to.sendgridcfc.helpers.mail()
  .from( '[email protected]' )
  .subject( 'Sending with SendGrid is Fun' )
  .to( '[email protected]' )
  .plain( 'and easy to do anywhere, even with ColdFusion');

sg.sendMail( mail );

Setup and Authentication

To get started with SendGrid, you'll need an API key. First, you'll need to create an account with SendGrid; then follow the instructions in the docs for creating an API key. The relevant section is located in your account within Settings > API Keys > Create API Key.

Once you have an API key, you can provide it to this wrapper manually when creating the component, as in the Quick Start example above, or via an environment variable named SENDGRID_API_KEY, which will get picked up automatically. This latter approach is generally preferable, as it keeps hardcoded credentials out of your codebase.

A Note on Email Validation

For reasons unclear to me, if you want to use SendGrid's email validation endpoint, you're required to set up a second, separate API key. Note that the email validation service is only available to users of SendGrid's "Pro" tier or higher. If you have a "Pro" account, you can generate a dedicated Email Validation API key in the same manner as the standard API key outlined above, and as explained in their documentation.

To provide the Email Validation API key to the wrapper, you can include it manually when creating the component:

sg = new sendgrid( apiKey = 'xxx', emailValidationApiKey = 'zzz' );

Alternatively, it will automatically be picked up via an environment variable named SENDGRID_EMAIL_VALIDATION_API_KEY. It will then be used automatically for requests to the email validation endpoint.

If you don't have a SendGrid "Pro" account and/or don't want to use SendGrid's email validation service, you can ignore this - there's no need to provide the emailValidationApiKey for using the other methods in the wrapper.

How to build an email

SendGrid enables you to do a lot with their endpoint for sending emails. This functionality comes with a tradeoff: a more complicated mail object that many other transactional email providers. So, following the example of their official libraries, I've put together a mail helper to make creating and manipulating the mail object easier.

As seen in the Quick Start example, a basic helper can be created via chaining methods:

mail = new helpers.mail().from( '[email protected]' ).subject( 'Hi, I love your emails' ).to( '[email protected]' ).html( '<p>Hi,</p><p>Thanks for all your emails</p>');

Alternatively, you can create the basic object with arguments, on init:

from = '[email protected]';
subject = 'Hi, I love your emails';
to = '[email protected]';
content = '<p>Hi,</p><p>Thanks for all your emails</p>';
mail = new helpers.mail( from, subject, to, content );

Note that for this API wrapper, the assumption when the content argument is passed in to init(), is that it is HTML, and that both html and plain text should be set and sent.

The from, subject, to, and message content, whether plain or html, are minimum required fields for sending an email.

I've found two places where the /mail/send endpoint JSON body are explained, and the (77!) possible parameters outlined. Familiarizing yourself with these will be of great help when using the API: V3 Mail Send API Overview and Mail Send Endpoint Documentation.

sendgrid.cfc Reference Manual

A full reference manual for all public methods in sendgrid.cfc can be found in the docs directory, here.

---

Reference Manual for helpers.mail

The reference manual for all public methods in helpers/mail.cfc can be found in the docs directory, in mail.md.

Reference Manual for helpers.campaign

The reference manual for all public methods in helpers/campaign.cfc can be found in the docs directory, in campaign.md.

Reference Manual for helpers.sender

The reference manual for all public methods in helpers/sender.cfc can be found in the docs directory, in sender.md.

Reference Manual for helpers.domain

The reference manual for all public methods in helpers/domain.cfc can be found in the docs directory, in domain.md.

Reference Manual for helpers.webhook

The reference manual for all public methods in helpers/webhook.cfc can be found in the docs directory, in webhook.md.

Questions

For questions that aren't about bugs, feel free to hit me up on the CFML Slack Channel; I'm @mjclemente. You'll likely get a much faster response than creating an issue here.

What versions of ColdFusion are required to use this project?

Ideally, this project would work with the currently supported versions of ColdFusion - at the time I'm writing this, that's Adobe ColdFusion 2018+ and Lucee 5.3+. It may work with earlier versions, but no promises.

Contributing

👍 🎉 First off, thanks for taking the time to contribute! 🎉 👍

Before putting the work into creating a PR, I'd appreciate it if you opened an issue. That way we can discuss the best way to implement changes/features, before work is done.

Changes should be submitted as Pull Requests on the develop branch.