BoxLang 🚀 A New JVM Dynamic Language Learn More...

SendGridProtocol

v6.0.0 Modules

Send Grid Protocol

Build Status

A cbmailservices protocol for sending email via Send Grid

In cbmailservices parlance, a protocol is a method of sending an email. Protocols can be switched out based on environment settings making it easy to log a mail to a file in development, send it to an in-memory store for asserting against in tests, and sending to real services in production.

Configuration

You can configure SendGrid as your protocol inside your mailsettings in your config/ColdBox.cfc. It is recommended you store your API key outside version control in either server ENV settings or Java properties. This approach also lets you easily swap out dev and production keys based on the environment.

mailsettings = {
	from = "[email protected]",
	tokenMarker = "@",
	protocol = {
		class = "sendgridprotocol.models.protocols.SendGridProtocol",
		properties = {
			apiKey = application.system.getProperty( "SEND_GRID_KEY" )
		}
	}
};

Template Emails

To send an email using a SendGrid template, you need to set the mail type to template:

var mail = mailService.newMail(
    to = user.getEmail(),
    subject = "Welcome to my site!",
    type = "template"
);

Then set the body to the template id in SendGrid:

mail.setBody( templateId );

Any tokens to be parsed by the template can be set as normal:

mail.setBodyTokens( {
    "[%username%]" = interceptData.user.getUsername()
} );

Plain Emails

To send a plain text email, set the type to plain:

var mail = mailService.newMail(
    to = user.getEmail(),
    subject = "Welcome to my site!",
    type = "plain"
);

The body of the email is what will be sent.

mail.setBody( "My plain text email here.  I can still use @placeholders@, of course." );

Categories

You can attach a list or array of categories for your email by setting them on the additionalInfo.categories field of the mail.

mail.setAdditionalInfoItem( "categories", "marketing" );
mail.setAdditionalInfoItem( "categories", "lists,of,categories" );
mail.setAdditionalInfoItem( "categories", [ "or", "as", "an", "array" ] );

Custom Arguments

You can attach a struct of custom_args by setting them on the additionalInfo.customArgs field of the mail.

mail.setAdditionalInfoItem( "customArgs", {
    "orderNumber" = toString( orderNumber )
} );

Note: Due to a bug in SendGrid, numeric values are not allowed. Convert any numeric values to strings (toString) to avoid errors.

v6.0.0

24 Aug 2023 — 02:19: 08 UTC

BREAKING

  • *: fix: Change errorArray to messages in struct returned from Send (4d3684c)
  • build: Remove ACF10 support (7ba4ba2)

chore

  • build: Add semantic release (74e00da)

feat

  • api: Add cc, bcc, and replyto properties (0b6f6bb)

fix

  • api: Fix for cc and bcc and return messageid (#4) (ef87657)
  • compat: Fix Adobe compatibility (8010118)

other

  • *: chore: Pin commandbox-semantic-release version (17406a0)
  • *: fix: Use dynamic_template_data instead of substitutions (f08939f)
  • *: feat: Add additional send grid options (144c42f)
  • *: Log unknown SendGrid HTTP errors (590a463)
  • *: compat: Add a name for cbmailservices 2 compatibility (ac85692)
  • *: feat: Support for attachments (44f72cd)
  • *: fix: use our new ccs and bccs arrays (dd291f3)
  • *: fix: Ensure unique emails across to, cc, and bcc (f6c8a4e)
  • *: fix: Better normalizing a list of emails to an array (1180c2a)
  • *: chore: Migrate from Travis CI to GitHub Actions (28dc4c5)
  • *: fix: Split to, cc, and bcc on semicolons as well as commas (6cce921)
  • *: fix: Handle multiple to addresses (f4fdab7)
  • *: fix: Better gitignore directory detection (4cc5474)
  • *: chore: Use OpenJDK instead of OracleJDK (9b4a284)
  • *: chore: Use forgeboxStorage (ce80012)
  • *: 1.5.0 (33029fb)
  • *: 1.4.0 (2f699b1)
  • *: Use fromName if one exists (3e153d1)
  • *: Fix README for plain text emails (4e095aa)
  • *: Update docs for custom args (822451b)
  • *: 1.3.0 (0fe003d)
  • *: Add customArgs support (234b5f7)
  • *: 1.2.1 (2b0ae24)
  • *: Update README with usage and configuration instructions (d33b734)
  • *: 1.2.0 (1784edb)
  • *: Add support for Categories (#2) (f6c21c1)
  • *: 1.1.0 (276f71b)
  • *: Add automatic versioning package scripts (b645e46)
  • *: Added Subject to Mail packet (843484c)
  • *: Add Travis CI support (b442729)
  • *: Initial commit (afa54f3)

v4.0.0

26 Aug 2020 — 12:02: 18 UTC

BREAKING

  • build: Remove ACF10 support (7ba4ba2)

chore

  • build: Add semantic release (74e00da)

feat

  • api: Add cc, bcc, and replyto properties (0b6f6bb)

fix

  • api: Fix for cc and bcc and return messageid (#4) (ef87657)
  • compat: Fix Adobe compatibility (8010118)

other

  • *: fix: Handle multiple to addresses (f4fdab7)
  • *: fix: Better gitignore directory detection (4cc5474)
  • *: chore: Use OpenJDK instead of OracleJDK (9b4a284)
  • *: chore: Use forgeboxStorage (ce80012)
  • *: 1.5.0 (33029fb)
  • *: 1.4.0 (2f699b1)
  • *: Use fromName if one exists (3e153d1)
  • *: Fix README for plain text emails (4e095aa)
  • *: Update docs for custom args (822451b)
  • *: 1.3.0 (0fe003d)
  • *: Add customArgs support (234b5f7)
  • *: 1.2.1 (2b0ae24)
  • *: Update README with usage and configuration instructions (d33b734)
  • *: 1.2.0 (1784edb)
  • *: Add support for Categories (#2) (f6c21c1)
  • *: 1.1.0 (276f71b)
  • *: Add automatic versioning package scripts (b645e46)
  • *: Added Subject to Mail packet (843484c)
  • *: Add Travis CI support (b442729)
  • *: Initial commit (afa54f3)

v2.0.1

07 Feb 2018 — 12:47: 35 UTC

fix

  • api: Fix for cc and bcc and return messageid (#4) (ef87657)

v2.0.0

06 Feb 2018 — 03:50: 57 UTC

BREAKING

  • build: Remove ACF10 support (7ba4ba2)

chore

  • build: Add semantic release (74e00da)

feat

  • api: Add cc, bcc, and replyto properties (0b6f6bb)

fix

  • compat: Fix Adobe compatibility (8010118)

Use It

$ box install send-grid-protocol

How do I do this?

Collaborators 0

No collaborators yet.

Links

     

Stats

  • {{ getFullDate("2016-09-08T17:16:15Z") }}
  • {{ getFullDate("2023-08-24T02:19:09Z") }}
  • 7,415
  • 36,328
Report Abuse