notifuse-cfml

notifuse-cfml is a CFML library for interacting with the Notifuse API. Notifuse is a modern, self-hosted emailing platform that allows you to send newsletters and transactional emails. It can use plain SMTP or integrate with third-party email delivery services like Amazon SES, SendGrid, Postmark, and others.

Installation

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

$ box install notifusecfml

Alternatively the git repository can be cloned.

Standalone Usage

Once the library has been installed, the core notifuse component can be instantiated directly:

notifuse = new path.to.notifusecfml.notifuse(
    apiKey = 'YOUR_NOTIFUSE_API_KEY',
    baseUrl = 'https://demo.notifuse.com'
);

ColdBox Module

To use the library as a ColdBox Module, add the init arguments to the moduleSettings struct in config/Coldbox.cfc:

moduleSettings = {
    notifusecfml: {
        apiKey: 'YOUR_NOTIFUSE_API_KEY',
        baseUrl: 'https://demo.notifuse.com'
    }
}

You can subsequently reference the library via the injection DSL: notifuse@notifusecfml:

property name="notifuse" inject="notifuse@notifusecfml";

Getting Started

<!--- Send a simple transactional message --->
<cfscript>
	x = notifuse.transactionalSend(
		workspace_id = 'my_workspace',
		id = 'welcome_template',
		contact = {
			email = '[email protected]'
		},
		data = {
			'greeting' = 'Hi Tom',
		}
	);
</cfscript>

<!--- Send a transactional message with more contact details, data to be used in the template, and a file attachment --->
<cfscript>
	x = notifuse.transactionalSend(
		workspace_id = 'my_workspace',
		id = 'another_template',
		contact = {
			email = '[email protected]',
			first_name = 'Tom',
			last_name = 'Thompson',
			external_id = 'user_12345'
		},
		data = {
			'greeting' = 'Hi Tom',
			'interested_in' = 'eBikes',
			'company_contact' = 'Stacey'
		},
		email_options = {
			attachments = [
				{
					filename = 'attach_me.md',
					content = toBase64( fileReadBinary( expandPath( 'attach_me.md' ) ) ),
					content_type = 'text/markdown'
				}
			]
		}
	);
</cfscript>

Configuration

There are two required config parameters: your Notifuse apiKey and baseUrl. The apiKey parameter is your Notifuse API key, which can be generated in the Notifuse admin interface under Settings > Team > Create API Key. The baseUrl parameter is the URL of your Notifuse instance.

Methods Available

notifuse-cfml currently covers these methods of the Notifuse API:

Category	endpoints supported
Transactional	transactional.send
Contacts	contacts.list
	contacts.count
	contacts.upsert
	contacts.getByEmail
	contacts.getByExternalID
	contacts.import
	contacts.delete
Lists	contactLists.updateStatus
	subscribe
	lists.subscribe
Broadcasts	broadcasts.list
	broadcasts.get
	broadcasts.create

Todo

• Add support for remaining Notifuse API endpoints

Acknowledgements

This project was inspired by stripecfml created by jcberquist.