CfMailGun

A CFML Client for the MailGun API

Project maintained by DominicWatson Hosted on GitHub Pages — Theme by mattgraham

This CFML client enables straightforward interaction with the MailGun API in your Railo, Open BlueDragon and Adobe ColdFusion applications.

The client is implemented as a single CFC. Instantiating the component can be achieved minimally with:

mailGunClient = new MailGunClient( apiKey = myPrivateApiKey );

API Reference

Instantiating the client

init()

Instantiates the API client. The client is designed as a singleton, so you are safe to store the instance in a permanent scope (i.e. the application scope). Returns the newly instantiated instance.

Input arguments

Name Type Required Description
apiKey string Yes Private API Key of your MailGun account
defaultDomain string No Optional, default domain to use in all API calls that pertain to a domain. Particulary useful if the instance is only intended to be used with a single domain.
baseUrl string No Optional, default is https://api.mailgun.net/v2. Should the endpoint change, you can pass it here (i.e. new version or mirrored service)
forceTestMode boolean No Optional, default is false. Whether or not to force all relevant API calls into test mode. This can be useful for staging environments when you want to ensure that no emails are accidentally sent to third parties, for example.
httpTimeout numeric No Optional, default 60. Maximum time in seconds to wait for a response from REST API calls.

Messages

SendMessage()

Sends a message by assembling it from the components. Returns the ID of the sent message if successful.

Input arguments

Name Type Required Description
domain string Yes/No Mailgun registered domain through which you want to send the message. If the client has been instantiated with a default domain, this argument is optional, otherwise required.
from string Yes Email address for From header
to string Yes Email address of the recipient(s). Example: Bob <[email protected]>. You can use commas to separate multiple recipients.
cc string No Same as To but for Cc
bcc string No Same as To but for Cc
subject string Yes Message subject
text string Yes Body of the message. (text version)
html string Yes Body of the message. (HTML version)
attachments array No Array of file paths to be added as attachments to the message
inlineAttachments array No Array of file paths to be added as inline attachments to the message. Can be used to send inline images (see example).
testMode boolean No Whether or not to send in test mode (MailGun will receive messages but not forward them on). Default is false. However, if the client has been instantiated with the forceTestMode option, then the value of this argument will be ignored and the message will always be sent in test mode.
tags array No Array of labels with which to "tag" the message. These can be used in reporting, etc.
campaign string No ID string of the MailGun campaign to associate this message with.
dkim boolean No Enables/disables DKIM signatures on per-message basis.
deliveryTime date No Desired time of delivery. Note: Messages can be scheduled for a maximum of 3 days in the future.
tracking boolean No Toggles tracking on a per-message basis
clickTracking boolean / string No Toggles clicks tracking on a per-message basis. Has higher priority than domain-level setting. Pass true/false or "htmlOnly".
openTracking boolean No Toggles opens tracking on a per-message basis. Has higher priority than domain-level setting.
customHeaders struct No A structure of custom header key value pairs. These headers will be sent along with the message. e.g. if you send { cmsId = 4573457 }, an email header named X-cmsId will be sent with a value of 4573457
customVariables struct No A structure of arbitrary custom data to attach to the message. This data will be sent as JSON in a mail header named X-Mailgun-Variables and will also be forwarded on to any Webhooks, etc. pertaining to the message

Campaigns

ListCampaigns()

Returns the list of campaigns created for a given domain.

Input arguments

Name Type Required Description
domain string Yes/No Mailgun registered domain for which to retrieve the list of campaigns. If the client has been instantiated with a default domain, this argument is optional, otherwise required.
limit number No Optional, default is 100. Limits the number of results to return.
skip number No Optional, default is 0. Offsets the results to return (used in conjuction with the limit argument to paginate results).

GetCampaign()

Returns a single campaign for a given domain. Information returned includes summary statistics.

Input arguments

Name Type Required Description
domain string Yes/No Mailgun registered domain for which to retrieve the campaign. If the client has been instantiated with a default domain, this argument is optional, otherwise required.
id string Yes ID of the campaign you wish to retrieve

CreateCampaign()

Creates a new campaign under a given domain. Note, that it will not create a new campaign, if the limit for account is reached - old campaigns must be deleted first. Returns a success message plus the details of the newly created campaign

Input arguments

Name Type Required Description
domain string Yes/No Mailgun registered domain in which to create the campaign. If the client has been instantiated with a default domain, this argument is optional, otherwise required.
name string Yes Name of the campaign
id string No ID of the campaign you wish to create. If not supplied, MailGun will generate an ID and return it along with the result.

UpdateCampaign()

Updates the name and/or id of an existing campaign under a given domain. Returns a success message plus the details of the updated campaign

Input arguments

Name Type Required Description
domain string Yes/No Mailgun registered domain in which to update the campaign. If the client has been instantiated with a default domain, this argument is optional, otherwise required.
id string Yes Existing ID of the campaign you wish to update
name string No New name of the campaign
newId string No New ID for the campaign

DeleteCampaign()

Deletes the given campaign. Returns a success message plus the ID of the deleted campaign

Input arguments

Name Type Required Description
domain string Yes/No Mailgun registered domain in which to delete the campaign. If the client has been instantiated with a default domain, this argument is optional, otherwise required.
id string Yes Existing ID of the campaign you wish to delete

Mailing lists

ListMailingLists()

Returns the list of mailing lists associated with the account.

Input arguments

Name Type Required Description
limit number No Optional, default is 100. Limits the number of results to return.
skip number No Optional, default is 0. Offsets the results to return (used in conjuction with the limit argument to paginate results).

GetMailingList()

Returns the mailing list matching the email address supplied.

Input arguments

Name Type Required Description
address string Yes Email address of the mailing list to retrieve

CreateMailingList()

Creates a new mailing list. Returns confirmation message and details of the newly created mailing list.

Input arguments

Name Type Required Description
address string Yes A valid email address for the mailing list, e.g. [email protected], or Developers <[email protected]>. Domain must match a domain registered with MailGun.
name string No Optional, mailing list name, e.g. Developers.
description string No Optional, a description
accessLevel string No Optional, list access level, one of: readonly (default), members, everyone

UpdateMailingList()

Update mailing list properties, such as address, description or name. Returns confirmation message and updated details of the mailing list.

Input arguments

Name Type Required Description
address string Yes Email address of the mailing list you wish to update
newAddress string Yes Optional, new email address for the list
name string No Optional, mailing list name, e.g. Developers.
description string No Optional, a description
accessLevel string No Optional, list access level, one of: readonly (default), members, everyone

DeleteMailingList()

Deletes a mailing list. Returns confirmation message and email address of the deleted mailing list.

Input arguments

Name Type Required Description
address string Yes Email address of the mailing list you wish to delete

ListMailingListMembers()

Returns the list of mailing list members.

Input arguments

Name Type Required Description
address string Yes Email address of the mailing list from which to fetch the members
subscribed boolean No Optional, filter members on whether or not they are subscribed. If not set, all members will be returned
limit number No Optional, default is 100. Limits the number of results to return.
skip number No Optional, default is 0. Offsets the results to return (used in conjuction with the limit argument to paginate results).

GetMailingListMember()

Returns a mailing list member.

Input arguments

Name Type Required Description
listAddress string Yes Email address of the mailing list from which to fetch the member
memberAddress string Yes Email address of the member to fetch

CreateMailingListMember()

Adds a member to the mailing list. Returns a confirmation message along with details of the newly created member.

Input arguments

Name Type Required Description
listAddress string Yes Email address of the mailing list to which to add the member
memberAddress string Yes Email address of the new member
name string No Optional, member name
vars struct No Optional, structure of custom variables to save against the member
subscribed boolean No Optional, whether or not the member is subscribed. Default is true
upsert boolean No Optional, whether to update existing record when found or throw an error (default).

UpdateMailingListMember()

Updates a mailing list member with given properties. Won’t touch the property if it’s not passed in. Returns a confirmation message along with updated details of the member.

Input arguments

Name Type Required Description
listAddress string Yes Email address of the mailing list in which the member exists
memberAddress string Yes Existing email address of the member
newAddress string No Optional, new email address of the member
name string No Optional, member name
vars struct No Optional, structure of custom variables to save against the member
subscribed boolean No Optional, whether or not the member is subscribed. Default is true

DeleteMailingListMember()

Delete a mailing list member. Returns a confirmation message along with email address of the deleted member.

Input arguments

Name Type Required Description
listAddress string Yes Email address of the mailing list form which the member should be removed
memberAddress string Yes Email address of the member to delete

BulkCreateMailingListMembers()

Adds multiple members, up to 1,000 per call, to a Mailing List. Returns a confirmation message along with the updated details of the list (i.e. new member count).

Input arguments

Name Type Required Description
listAddress string Yes Email address of the mailing list to which to add the members
members array Yes Array of structs containing member details. Each member struct must contain an address key, containing the email address of the member, and optionally may contain name and vars keys. Invalid structs and keys will be ignored.
subscribed boolean Yes Whether or not the members should be subscribed