FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...


v0.5.2 Public


A CFML wrapper for the MailGun API

This project borrows heavily from the API framework built by jcberquist with stripecfc. Because it draws on that project, it is also licensed under the terms of the Apache License, Version 2.0.

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 mailguncfc

If you can't use CommandBox, all you need to use this wrapper as a standalone component is the mailgun.cfc file; just add it 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 mailguncfc in whichever directory you have chosen and can then be instantiated directly like so:

mailgun = new mailguncfc.mailgun(
  secretApiKey = 'key-xxx',
  publicApiKey = 'pubkey-xxx',
  domain = ''

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 = {
  mailguncfc = {
    secretApiKey  = 'key-xxx',
    publicApiKey  = 'pubkey-xxx',
    domain        = ''

You can then leverage the CFC via the injection DSL: [email protected]:

property name="mailgun" inject="[email protected]";

Available Methods

Note that the Mailgun API has more methods available. This is a list of those currently available in this wrapper. I'll be adding more as time permits and needs dictate.


validate( required string address, boolean mailbox_verification = false, boolean private = true )


sendMessage( string domain = variables.domain, required string from, required string to, string cc, string bcc, string subject, string text = "", string html = "", any attachment, any inline, struct o = { }, struct h = { }, struct v = { }, any recipient_variables )

getStoredMessage( required string messageUrl )


getBounces( string domain = variables.domain, numeric limit = 100 )


getStats( string domain = variables.domain, required string event, date start = '#now()#-7', date end = '#now()#', string resolution = 'day', string duration )

Mailing Lists:


getList( required string listaddress, numeric limit = 100, numeric skip = 0 )

createList( required string address, string name = "", string description = "", access_level = "readonly" )

createListMember( required string listaddress, required string address, string name, string vars, boolean subscribed = true, boolean upsert = false )

createListMembers( required string listaddress, required json members, boolean upsert = false )

Mailgun Account Credentials

Your account credentials can be found on the dashboard of your Mailgun account:

Mailgun API Keys

Currently both your Secret API Key and your Public API Key must be provided. The Secret API Key is used for most operations. In prior versions, email validation calls used the Public API Key. However, now that Mailgun has moved to a usage based pricing model for their email validation, the default for email validation calls is also to use the Secret API Key. The Public API Key requirement will likely be removed in later versions. It's currently included, so that calls can explicitly be made to the public endpoint of the email validation API.


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.



Thanks @coldfumonkeh


  • Ability to use as a ColdBox module


Thanks @ericleversen


  • recipient_variables support to sendMessage()



  • Method getStoredMessage(), to retrieve an inbound message that has been stored via the Mailgun's store() action, using the URL found in the stored event
  • Option getStats(), to return a domain's event statistics



  • Option mailbox_verification, to validate(), to enable a mailbox verification check to be performed against the address.
  • Option private, to validate(), to override default and call public API endpoint


  • validate() now defaults to the private API endpoint


Thanks @mjhagen


  • Two list management functions:
  • createList()
  • createListMembers()


  • Expanded the error reporting by deserializing the returned message and adding that to the error detail.

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
0.5.2 Sep 12 2018 07:58 PM Sep 12 2018 07:58 PM
Version History
0.5.1 May 30 2018 07:27 PM May 30 2018 07:27 PM
0.5.0 May 04 2018 05:55 AM May 04 2018 05:55 AM
0.4.2 Apr 26 2018 10:00 PM Apr 26 2018 10:00 PM
0.4.1 Mar 03 2018 08:07 PM Mar 03 2018 08:07 PM
0.3.0 Feb 23 2018 03:56 PM Feb 23 2018 03:56 PM


  •   Matthew Clemente
  • Published
  • 0.5.2 is the latest of 6 release(s)
  • Published on Sep 12 2018 07:58 PM
No collaborators yet.
  • Feb 23 2018 03:56 PM
  • Sep 12 2018 07:58 PM
  • 664
  • 0
  • 167