Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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.


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

Table of Contents


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 apiKey = 'xxx' );

mail = new
  .from( '' )
  .subject( 'Sending with SendGrid is Fun' )
  .to( '' )
  .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( '' ).subject( 'Hi, I love your emails' ).to( '' ).html( '<p>Hi,</p><p>Thanks for all your emails</p>');

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

from = '';
subject = 'Hi, I love your emails';
to = '';
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

Reference Manual for helpers.campaign

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

Reference Manual for helpers.sender

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

Reference Manual for helpers.domain

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

Reference Manual for helpers.webhook

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


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.


👍🎉 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.


A CFML wrapper for the SendGrid API






Sponsor this project


No packages published