A CFML wrapper for the SendGrid API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
helpers
LICENSE
ModuleConfig.cfc
README.md
box.json
sendgrid.cfc

README.md

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, such as xero-cfml and aws-cfml. Because it draws on those projects, it is also licensed under the terms of the MIT license.

Table of Contents

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' );

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";

Quick Start

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

sg = new sendgrid( apiKey = 'xxx' );

mail = new helpers.mail()
	.from( 'test@example.com' )
	.subject( 'Sending with SendGrid is Fun' )
	.to( 'test@example.com' )
	.plain( 'and easy to do anywhere, even with ColdFusion');

sg.sendMail( mail );

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( 'name@youremail.com' ).subject( 'Hi, I love your emails' ).to( 'myfriend@email.com' ).html( '<p>Hi,</p><p>Thanks for all your emails</p>');

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

from = 'name@youremail.com';
subject = 'Hi, I love your emails';
to = 'myfriend@email.com';
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

Mail Send Reference

View SendGrid Docs for Sending Mail

sendMail( required component mail )

Sends email, using SendGrid's REST API. The mail argument must be an instance of the helpers.mail component. See the quick start for sending and how to build an email for more information on how this is used.


Blocks API Reference

View SendGrid Docs for Blocks

listBlocks( any start_time = 0, any end_time = 0, numeric limit = 0, numeric offset = 0 )

Retrieve a list of all email addresses that are currently on your blocks list. The start_time and end_time arguments, if numeric, are assumed to be unix timestamps. Otherwise, they are presumed to be a valid date that will be converted to unix timestamps automatically.

getBlock( required string email )

Retrieve a specific email address from your blocks list.


Bounces API Reference

View SendGrid Docs for Bounces

listBounces( any start_time = 0, any end_time = 0, numeric limit = 0, numeric offset = 0 )

Retrieve a list of bounces that are currently on your bounces list. The start_time and end_time arguments, if numeric, are assumed to be unix timestamps. Otherwise, they are presumed to be a valid date that will be converted to unix timestamps automatically.

getBounce( required string email )

Retrieve specific bounce information for a given email address.


Campaigns API Reference

View SendGrid Docs for Campaigns

createCampaign( required any campaign )

Allows you to create a marketing campaign. The campaign argument should be an instance of the helpers.campaign component. However, if you want to create and pass in the struct or json yourself, you can. See the campaign helper reference manual for more information on how this is used.

listCampaigns()

Retrieve a list of all of your campaigns.

getCampaign( required numeric id )

Retrieve a single campaign by ID.

deleteCampaign( required numeric id )

Delete a single campaign by ID.

updateCampaign( required numeric id, required any campaign )

Update a campaign by ID. The campaign arguments should be an instance of the helpers.campaign component. However, if you want to create and pass in the struct or json yourself, you can. See the campaign helper reference manual for more information on how this is used.


Contacts API - Recipients Reference

View SendGrid Docs for Contacts API - Recipients

addRecipients( required array recipients )

Add Marketing Campaigns recipients. Note that it also appears to update existing records, so it basically functions like a PATCH. The recipients arguments is an array of objects, with at minimum, and 'email' key/value.

addRecipient( required any recipient, string first_name = '', string last_name = '', struct customFields = {} )

Convenience method for adding a single recipient at a time. The recipient arguments facilitates two means of adding a recipient. You can pass in a struct with key/value pairs providing all relevant recipient information. Alternatively, you can use this to simply pass in the recipient's email address, which is all that is required. The customFields keys correspond to your custom field names, along with their assigned values.

updateRecipients( required array recipients )

Update one or more Marketing Campaign recipients. Note that it will also add non-existing records. The recipients arguments is an array of objects, with at minimum, and 'email' key/value.

updateRecipient( required any recipient, string first_name = '', string last_name = '', struct customFields = {} )

Convenience method for updating a single recipient at a time. The recipient arguments facilitates two means of adding a recipient. You can pass in a struct with key/value pairs providing all relevant recipient information. Alternatively, you can use this to simply pass in the recipient's email address, which is all that is required. The customFields keys correspond to your custom field names, along with their assigned values.

getRecipientUploadStatus()

Check the upload status of a Marketing Campaigns recipient.

deleteRecipient( required string id )

Delete a single recipient with the given ID from your contact database. The id arguments can be the recipient ID or email address (which will be converted to the recipient ID)

deleteRecipients( required array recipients )

Deletes one or more recipients. This is an incomplete implementation of the SendGrid API. Technically, this should send a DELETE request to /contactdb/recipients, with an array of IDs as the body. But ColdFusion doesn't currently include the request body in DELETE calls. So we loop the recipients through the individual delete method. The recipients arguments is an array of the recipient IDs you want to delete. You can also provide their email addresses, and they will be converted to recipient IDs

listRecipients( numeric page = 0, numeric pageSize = 0 )

Retrieve all of your Marketing Campaign recipients.

getRecipient( required string id )

Retrieve a single recipient by ID from your contact database. The id argument can be the recipient ID or email address (which will be converted to the recipient ID).

listListsByRecipient( required string id )

Retrieve the lists that a given recipient belongs to. The id argument can be the recipient ID or email address (which will be converted to the recipient ID).

getBillableRecipientCount()

Retrieve the number of Marketing Campaigns recipients that you will be billed for.

getRecipientCount()

Retrieve the total number of Marketing Campaigns recipients.

searchRecipients( required string fieldName, any search = '' )

Perform a search on all of your Marketing Campaigns recipients. The fieldName argument is the name of a custom field or reserved field. The search argument is the value to search for within the specified field. Date fields must be unix timestamps. Currently, searches that are formatted as a U.S. date in the format mm/dd/yyyy (1-2 digit days and months, 1-4 digit years) are converted automatically.


Contacts API - Segments Reference

View SendGrid Docs for Contacts API - Segments

createSegment( required string name, required array conditions, numeric listId = 0 )

Create a segment using search conditions.

The conditions argument is an array of structs making up the search conditions that define this segment. Read SendGrid documentation for specifics on how to segment contacts.

The listId argument indicates the list from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list.

listSegments()

Retrieve all of your segments.

getSegment( required numeric id )

Retrieve a single segment with the given ID.

updateSegment( required numeric id, string name = '', array conditions = [], numeric listId = 0 )

Update a segment. Functions similarly to createSegment(), but you only need to include the parameters you are updating.

Note that the listId argument can be used to change the list for this segment, but once a list has been set, the segment cannot be returned to the main contactdb.

deleteSegment( required numeric id )

Delete a segment from your recipients database.

listRecipientsBySegment( required numeric id )

Retrieve all of the recipients in a segment with the given ID.


Contacts API - Custom Fields Reference

View SendGrid Docs for Contacts API - Custom Fields

createCustomField( required string name, required string type )

Create a custom field. For the type arguments, the allowed values are 'text', 'date', and 'number'.

listCustomFields()

Retrieve all custom fields.

getCustomField( required numeric id )

Retrieve a custom field by ID.

deleteCustomField( required numeric id )

Delete a custom field by ID.

listReservedFields()

List all fields that are reserved and can't be used for custom field names.


Contacts API - Lists Reference

View SendGrid Docs for Contacts API - Lists

createList( required string name )

Create a list for your recipients.

listLists()

Retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.

deleteLists( required array lists )

Delete multiple recipient lists. This is an incomplete implementation of the SendGrid API. Technically, this should send a DELETE request to /contactdb/lists, with an array of IDs as the body. But ColdFusion doesn't currently include the request body in DELETE calls. So we loop the lists through the individual delete method. The recipients argument is an array of the list IDs you want to delete.

deleteList( required numeric id )

Delete a single list with the given ID from your contact database.

getList( required numeric id )

Retrieve a single recipient list by ID.

updateList( required numeric id, required string name )

Update the name of one of your recipient lists.

listRecipientsByList( required numeric id, numeric page = 0, numeric pageSize = 0 )

Retrieve all recipients on the list with the given ID.

addRecipientToList( required numeric listId, required string recipientId )

Add a single recipient to a list. The recipientId argument can be the recipient ID or email address (which will be converted to the recipient ID).

deleteRecipientFromList( required numeric listId, required string recipientId )

Delete a single recipient from a list. The recipientId argument can be the recipient ID or email address (which will be converted to the recipient ID).

addRecipientsToList( required numeric listId, required array recipients )

Add multiple recipients to a list. The recipients argument is an array of recipient IDs or email addresses. The first element of the array is checked to determine if it is an array of IDs or email addresses.


Invalid Emails API Reference

View SendGrid Docs for Invalid Emails

listInvalidEmails( any start_time = 0, any end_time = 0, numeric limit = 0, numeric offset = 0 )

Retrieve a list of invalid emails that are currently on your invalid emails list. The start_time and end_time arguments, if numeric, are assumed to be unix timestamps. Otherwise, they are presumed to be a valid date that will be converted to unix timestamps automatically.

getInvalidEmail( required string email )

Retrieve information about a specific invalid email address.


Sender Identities API Reference

View SendGrid Docs for Sender Identities

createSender( required any sender )

Allows you to create a new sender identity. The sender argument should be an instance of the helpers.sender component. However, if you want to create and pass in the struct or json yourself, you can. See the sender helper reference manual for more information on how this is used.

listSenders()

Retrieve a list of all sender identities that have been created for your account.

updateSender( required numeric id, required any sender )

Update a sender identity by ID. The sender argument should be an instance of the helpers.sender component. However, if you want to create and pass in the struct or json yourself, you can. See the sender helper reference manual for more information on how this is used.

deleteSender( required numeric id )

Delete a single sender identity by ID.

resendSenderVerification( required numeric id )

Resend a sender identity verification email.

getSender( required numeric id )

Retrieve a single sender identity by ID.


Suppressions - Suppressions Reference

View SendGrid Docs for Suppressions - Suppressions

addEmailsToUnsubscribeGroup( required numeric id, required array emails )

Add email addresses to an unsubscribe group. If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.

addEmailToUnsubscribeGroup( required numeric id, required string email )

Convenience method for adding a single email address to an unsubscribe group. Delegates to addEmailsToUnsubscribeGroup()

listEmailsByUnsubscribeGroup( required numeric id )

Retrieve all suppressed email addresses belonging to the given group.

deleteEmailFromUnsubscribeGroup( required numeric id, required string email )

Remove a suppressed email address from the given suppression group.

listAllSupressions()

Retrieve a list of all suppressions.

listUnsubscribeGroupsByEmail( required string email )

Appears to slightly differ from the documentation. Returns all supressions groups, with an indication if the email address is supressed or not.

searchUnsubscribeGroupForEmails( required numeric id, required array emails )

Search a suppression group for multiple suppressions.

searchUnsubscribeGroupForEmail( required numeric id, required string email )

Convenience method for searching for a single email within an unsubscribe group. Delegates to searchUnsubscribeGroupForEmails()


Suppressions - Unsubscribe Groups Reference

View SendGrid Docs for Suppressions - Unsubscribe Groups

createUnsubscribeGroup( required string name, required string description, boolean isDefault )

Create a new unsubscribe suppression group. The name and description arguments are both required. They can be seen by recipients on the unsubscribe landing page. SendGrid enforces the max length of these arguments by silently trimming their values to 30 and 100 characters, respectively.

listUnsubscribeGroups()

Retrieve a list of all suppression groups created by this user.

getUnsubscribeGroup( required numeric id )

Retrieve a single suppression group.

updateUnsubscribeGroup( required numeric id, string name = '', string description = '', required boolean isDefault )

Update an unsubscribe suppression group. The name and description arguments can be seen by recipients on the unsubscribe landing page. SendGrid enforces the max length of these arguments by silently trimming their values to 30 and 100 characters, respectively. For updates, the isDefault argument is required by this library, because if you don't supply it, SendGrid assumes false, which is confusing.

deleteUnsubscribeGroup( required numeric id )

Delete a suppression group.


Cancel Scheduled Sends Reference

View SendGrid Docs for Cancel Scheduled Sends

generateBatchId()

Generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.


Spam Reports API Reference

View SendGrid Docs for Spam Reports

listSpamReports( any start_time = 0, any end_time = 0, numeric limit = 0, numeric offset = 0 )

Retrieve a list of spam reports that are currently on your spam reports list. The start_time and end_time arguments, if numeric, are assumed to be unix timestamps. Otherwise, they are presumed to be a valid date that will be converted to unix timestamps automatically.

getSpamReport( required string email )

Retrieve a specific spam report by email address.


Reference Manual for helpers.mail

This section documents every public method in the helpers/mail.cfc file. A few notes about structure, data, and usage:

  • Unless indicated, all methods are chainable.
  • Top level parameters are referred to as "global" or "message level", as opposed to personalized parameters. As the SendGrid docs state: "Individual fields within the personalizations array will override any other global, or “message level”, parameters that are defined outside of personalizations."
  • Email address parameters can be passed in either as strings or structs.
    • When passed as a string, they can be in the format: Person <name@email.com>, in order to pass both name and email address.
    • When passed as a struct, the keys should be email and name, respectively. Only email is required.

from( required any email )

replyTo( required any email )

subject( required string subject )

Sets the global subject. This may be overridden by personalizations[x].subject.

html( required string message )

Convenience method for adding the text/html content

plain( required string message )

Convenience method for adding the text/plain content

emailContent( required struct content, boolean doAppend = true )

Method for setting any content mime-type. The default is that the new mime-type is appended to the Content array, but you can override this and have it prepended. This is used internally to ensure that text/plain precedes text/html, in accordance with the RFC specs, as enforced by SendGrid.

plainFromHtml( string message = '' )

Convenience method for setting both text/html and text/plain at the same time. You can either pass in the HTML content as the message argument, and both will be set from it (using an internal method to strip the HTML for the plain text version), or you can call the method without an argument, after having set the HTML, and that will be used.

attachments( required array attachments )

Sets the attachments property for the global message. If any attachments were previously set, this method overwrites them.

addAttachment( required struct attachment )

Appends a single attachment to the message. The attachment argument is struct with at minimum keys for content and filename. View the SendGrid docs for the full makeup and requirements of the object: https://sendgrid.api-docs.io/v3.0/mail-send

attachFile( required string filePath, string fileName, string type, string disposition = 'attachment', string content_id )

A convenience method for appending a single file attachment to the message. All that is required is the relative or absolute path to an on-disk file. Its properties are used if the additional arguments aren't provided.

templateId( required string templateId )

Sets the id of a template that you would like to use for the message

section( required any section, any value )

Appends a single section block to the global message's sections property. I'd recommend reading up on the somewhat limited documentation SendGrid provides about sections and substitutions for more clarity on how they should be structured and used.

You can set a section by providing the section tag and replacement value separately, or by passing in a struct with a key/value pair; for example, { "-greeting-" : 'Welcome -first_name- -last_name-,' }.

sections( required struct sections )

Sets the sections property for the global message. If any sections were previously set, this method overwrites them.

header( required any header, any value )

Appends a single header to the global message's headers property. This can be overridden by a personalized header.

You can set a header by providing the header and value separately, or by passing in a struct with a key/value pair; for example, { "X-my-application-name" : 'testing' }.

headers( required struct headers )

Sets the headers property for the global message. Headers can be overridden by a personalized header. If any headers are set, this method overwrites them.

categories( required any categories )

Sets the category array for the global message. If categories are already set, this overwrites them. The argument can be passed in as an array or comma separated list. Lists will be converted to arrays

addCategory( required string category )

Appends a single category to the global message category array

customArg( required any arg, any value )

Appends a single custom argument on the global message's custom_args property. This can be overridden by a personalized custom argument.

You can set a custom argument by providing the argument's name and value separately, or by passing in a struct with a key/value pair; for example, { "Team": "Engineering" }.

customArgs( required struct args )

Sets the custom_args property for the global message. Custom arguments can be overridden by a personalized custom argument. If any custom arguments are set, this overwrites them.

sendAt( required date timeStamp )

Sets the global send_at property, which specifies when you want the email delivered. This may be overridden by the personalizations[x].send_at.

batchId( required string batchId )

Sets the global batch_id property, which represents a group of emails that are associated with each other. The sending of emails in a batch can be cancelled or paused. Note that you must generate the batchID value via the API.

mailSettings( required struct settings )

Sets the mail_settings property for the global message. If any mail settings were previously set, this method overwrites them. While this makes it possible to pass in the fully constructed mail settings struct, the preferred method of setting mail settings is by using their dedicated methods.

mailSetting( required any setting, any value )

Generic method for defining individual mail settings. Using the dedicated methods for defining mail settings is usually preferable to invoking this directly.

You can define a setting by providing the setting key and its value separately, or by passing in a struct with a key/value pair; for example, { "sandbox_mode" : { "enable" : true } }.

bccSetting( required boolean enable, string email = '' )

Sets the global mail_settings.bcc property, which allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent. Using the dedicated enable/disable bcc methods is usually preferable.

enableBcc( required string email )

Convenience method for enabling the bcc mail setting and setting the address

disableBcc()

Convenience method for disabling the bcc mail setting

bypassListManagementSetting( required boolean enable )

Sets the global mail_settings.bypass_list_management property, which allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. According to SendGrid, this should only be used in emergencies when it is absolutely necessary that every recipient receives your email. Using the dedicated enable/disable methods is usually preferable to invoking this directly

enableBypassListManagement()

Convenience method for disabling the bypass_list_management mail setting

disableBypassListManagement()

Convenience method for disabling the bypass_list_management mail setting

footerSetting( required boolean enable, string text = '', string html = '' )

Sets the global mail_settings.footer property, which provides the option for setting a default footer that you would like included on every email. Using the dedicated enable/disable methods is usually preferable.

enableFooter( required string text, required string html )

Convenience method for enabling the footer mail setting and setting the text/html

disableFooter()

Convenience method for disabling the footer mail setting

sandboxModeSetting( required boolean enable )

Sets the global mail_settings.sandbox_mode property, which allows allows you to send a test email to ensure that your request body is valid and formatted correctly. Sandbox mode is only used to validate your request. The email will never be delivered while this feature is enabled! Using the dedicated enable/disable methods is usually preferable to invoking this directly. You can read more here.

enableSandboxMode()

Convenience method for disabling the sandbox_mode mail setting

disableSandboxMode()

Convenience method for disabling the sandbox_mode mail setting

spamCheckSetting( required boolean enable, numeric threshold = 0, string post_to_url = '' )

Sets the global mail_settings.spam_check property, which allows you to test the content of your email for spam. Using the dedicated enable/disable methods is usually preferable.

enableSpamCheck( required numeric threshold, required string post_to_url )

Convenience method for enabling the spam_check mail setting and setting the threshold and post_to_url

disableSpamCheck()

Convenience method for disabling the spam_check mail setting

to( required any email )

Adds a new personalization envelope, with only the specified email address. The personalization can then be further customized with later commands. I found personalizations a little tricky. You can read more here.

addTo( required any email )

Adds an additional 'to' recipient to the current personalization envelope

addCC( required any email )

Adds an additional 'cc' recipient to the current personalization envelope. You need to add a 'to' recipient before using this.

addBCC( required any email )

Adds an additional 'bcc' recipient to the current personalization envelope. You need to add a 'to' recipient before using this.

withSubject ( required string subject )

Sets the subject for the current personalization envelope. This overrides the global email subject for these recipients. A basic personalization envelope (with a 'to' recipient) needs to be in place before this can be added.

withHeader ( any header, any value )

Functions like header(), except it adds the header to the current personalization envelope.

withHeaders( required struct headers )

Functions like headers(), except it sets the headers property for the current personalization envelope. If any personalized headers are set, this method overwrites them.

withSubstitution ( any substitution, any value )

Appends a substitution ( "substitution_tag" : "value to substitute" ) to the current personalization envelope. You can add a substitution by providing the tag and value to substitute, or by passing in a struct.

withSubstitutions( required struct substitutions )

Sets the substitutions property for the current personalization envelope. If any substitutions are set, this method overwrites them.

withCustomArg( required any arg, any value )

Functions like customArg(), except it adds the custom argument to the current personalization envelope.

withCustomArgs( required struct args )

Functions like customArgs(), except it sets the custom_args property for the current personalization envelope. If any personalized custom arguments are set, this method overwrites them.

withSendAt( required date timeStamp )

Functions like sendAt(), except it sets the desired send time for the current personalization envelope.

build()

The function that puts it all together and builds the body for /mail/send

Reference Manual for helpers.campaign

This section documents every public method in the helpers/campaign.cfc file. A few notes about structure, data, and usage:

  • Unless indicated, all methods are chainable.

title( required string title )

Sets the display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. This is the only required field for creating a campaign

subject( required string subject )

Sets the subject of your campaign that your recipients will see.

sender( required numeric id )

Sets who the email is "from", using the ID of the "sender" identity that you have created.

fromSender( required numeric id )

Included in order to provide a more fluent interface; delegates to sender()

useLists( required array lists )

Sets the IDs of the lists you are sending this campaign to. Note that you can have both segment IDs and list IDs. If any list Ids were previously set, this method overwrites them. The lists arguments can be passed in as an array or comma separated list. Lists will be converted to arrays.

useList( required numeric id )

Appends a single list Id to the array of List Ids that this campaign is being sent to.

useSegments( required any segments )

Sets the segment IDs that you are sending this list to. Note that you can have both segment IDs and list IDs. If any segment Ids were previously set, this method overwrites them. The segments argument can be passed in as an array or comma separated list. Lists will be converted to arrays.

useSegment( required numeric id )

Appends a single segment Id to the array of Segment Ids that this campaign is being sent to.

categories( required any categories )

Set an array of categories you would like associated to this campaign. If categories are already set, this overwrites them. The categories argument can be passed in as an array or comma separated list. Lists will be converted to arrays.

addCategory( required string category )

Appends a single category to campaigns array of categories.

suppressionGroupId( required numeric id )

Assigns the suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type. Note that you cannot provide both a suppression group Id and a custom unsubscribe url. The two are mutually exclusive.

useSuppressionGroup( required numeric id )

Included in order to provide a more fluent interface; delegates to suppressionGroupId()

customUnsubscribeUrl( required string uri )

This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from mailings. Using this takes the place of having SendGrid manage your suppression groups.

useCustomUnsubscribeUrl( required string uri )

Included in order to provide a more fluent interface; delegates to customUnsubscribeUrl()

ipPool( required string name )

The pool of IPs that you would like to send this email from. Note that your SendGrid plan must include dedicated IPs in order to use this.

fromIpPool( required string name )

Included in order to provide a more fluent interface; delegates to ipPool()

html( required string message )

Convenience method for adding the text/html content

htmlContent( required string message )

Redundant, but included for consistency in naming the methods for setting attributes. Delegates to html()

plain( required string message )

Convenience method for adding the text/plain content

plainContent( required string message )

Redundant, but included for consistency in naming the methods for setting attributes. Delegates to plain()

plainFromHtml( string message = '' )

Convenience method for setting both html and plain at the same time. You can either pass in the HTML content, and both will be set from it (using a method to strip the HTML for the plain text version), or you can call the method without an argument, after having set the HTML, and that will be used.

useDesignEditor()

The editor used in the UI. Because it defaults to code, it really only needs to be toggled to design

useCodeEditor()

The editor used in the UI. It defaults to code, so this shouldn't be needed, but it's provided for consistency.

build()

The function that puts it all together and builds the body for campaign related API operations.

Reference Manual for helpers.sender

This section documents every public method in the helpers/sender.cfc file. A few notes about structure, data, and usage:

  • Unless indicated, all methods are chainable.
  • Email address parameters can be passed in either as strings or structs.
    • When passed as a string, they can be in the format: Person <name@email.com>, in order to pass both name and email address.
    • When passed as a struct, the keys should be email and name, respectively.

nickname( required string nickname )

Sets the nickname for the sender identity. Not used for sending, but required.

from( required any email )

Set where the email will appear to originate from for your recipients. Note that, despite what the documentation says, both email address and name need to be provided. If a string is passed in and the name is not provided, the email address will be used as the name as well.

replyTo( required any email )

Set where your recipients will reply to. If a string is passed in and the name is not provided, the email address will be used as the name as well.

address( required string address )

Required. Sets the physical address of the sender identity.

address2( required string address )

Provides additional sender identity address information.

city( required string city )

Required.

state( required string state )

zip( required string zip )

country( required string country )

Required.

build()

The function that puts it all together and builds the body for sender related API operations

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.

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.