mailgun-es6

The goal of this is to create an up-to-date library that interacts with the Mailgun API using only native JS modules. If you are not using node 4.0.0+ please make sure you include the --harmony option. mailgun-es6 is MIT licensed.

Installation

$ npm install mailgun-es6

Set Up

var MailGun = require('mailgun-es6');
var mailGun = new MailGun({
  privateApi: 'Your Private API Key',
  publicApi: 'Your Public API Key',
  domainName: 'The domain on your account'
});

Usage

Messages

Sending Messages - POST /[domain]/messages

mailGun.sendEmail({
  to: ['to@email.com', 'sally@dally.com', 'bob@noemail.com'],
  from: 'from@email.com',
  subject: 'Email Subject',
  text: 'Email Text',
  attachment: {
    fType: 'text/plain',
    fLoc: __dirname + '/LICENSE'
  }
}[, domainName]);

Returns

promise(MailGun_Response, Rejection_Message)

The four required fields are above. Any valid Mailgun options can be passed here in addition to these 4 fields. The Domain name passed in the function will supersede the default domain name if specified. The Mailgun descriptions are below along with the current limitations of this library.

Parameter	Description
to	Email address of the recipient(s). Example: "Bob bob@host.com". You can use commas to separate multiple recipients. Although 'to' is the only required string, you can also submit 'cc' and 'bcc'
html	An HTML version of the message you are sending
o:tag	Tag string. See Tagging for more information.
o:campaign	Id of the campaign the message belongs to. See Campaign Analytics for details.
o:deliverytime	Desired time of delivery. See Date Format. Note: Messages can be scheduled for a maximum of 3 days in the future.
o:dkim	Enables/disabled DKIM signatures on per-message basis. Pass yes or no
o:testmode	Enables sending in test mode. Pass yes if needed. See Sending in Test Mode
o:tracking	Toggles tracking on a per-message basis, see Tracking Messages for details. Pass yes or no.
o:tracking-clicks	Toggles clicks tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes, no or htmlonly.
o:tracking-opens	Toggles opens tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes or no.
h:X-My-Header	h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-Header in this case). For example, h:Reply-To to specify Reply-To address.
v:my-var	v: prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See Attaching Data to Messages for more information.
attachment	This will send a file along with your email. fLoc needs ot be a valid file location. fType should be a valid MIME type.

Retrieving Stored Messages - GET domains/[domain]/messages

mailGun.getStoredMessages([msgId, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function works with both retrieving the list of stored messages as well as single stored messages. If no parameters as passed, it will return an array of objects are the stored messages. Internally, this calls Retrieving Events with a event=stored filter. For more control on returned events, use the retrieving events call. If a msgId is passed, then it will look for that specific message. Again, the domain parameter will overwrite the constructors domainName.

Deleting Stored Messages - DELETE domains/[domain]/messages

mailGun.deleteStoredMessages([msgId, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function deletes a stored message.

Domains

Retrieving Domain Information - GET /domains/[domain]

mailGun.getInformation([domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function will either retrieve all domain records for the associated account or a single domain if 'domain' is passed as a parameter.

Add New Domain - POST /domains

mailGun.addNewDomain('newDomain.com', 'smtpPassword', wildcard, 'spamAction');

Returns

promise(MailGun_Response, Rejection_Message)

This endpoint associates a new domain with a current Mailgun account. Spam action refers to either disable which will disable spam filtering and tag which will tag with a spam header. More information can be found about the Spam Filter. Wildcard enables the added account to also respond to subdomains. (e.g., kyle@sub.domain.com) It is recommended that all four fields are passed into the function, however the domain and password are the only required fields. spamAction will default to disable and wildCard will default to false.

Delete Domain - DELETE /domains

mailGun.deleteDomain(domainToDelete);

Returns

promise(MailGun_Response, Rejection_Message)

This method deletes a current domain associated with the account. domainToDelete is required and will not assume default domain as this is a destructive action.

Retrieving SMTP Credentials - GET /domains/[domain]/credentials

mailGun.getSmtpUsers([domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function will respond with the current SMTP credentials for the specified domain. If no domain is passed, it will return the domain set at object creation. This does not respond with the passwords. This only responds with a list of available logins.

Add SMTP Credentials - POST /domains[domain]/credentials

mailGun.addSmtpUser(username, password[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function adds a SMTP user to the account. SMTP users are not needed unless you're implementing a SMTP connection.

Update SMTP Credentials - PUT /domains[domain]/credentials/[login]

mailGun.updateSmtpUser(username, password[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function updates a current SMTP user for a domain. This will not 'upsert' a user. Also, Mailgun has limited changing only the password. To change the username, delete the target and create a new one.

Delete SMTP Credentials - DELETE /domains[domain]/credentials/[login]

mailGun.deleteSmtpUser(username[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes a current SMTP user.

Get Connection Settings - GET /domains/[domain]/connection

mailGun.getConnectionSettings([domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function returns the connection settings for a domain. The first setting (require_tls) is true if the domain is set to require a TLS connection to interact with the server. The second setting (skip_verfication) determines if the certificate and hostname verification should be skipped. See Update Connection Settings for full information.

Update Connection Settings - PUT /domains/[domain]/connection

mailGun.updateConnectionSettings(requireTLS, skipVerification[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

From the Mailgun Docs:

Parameter	Description
requireTLS	If set to True this requires the message only be sent over a TLS connection. If a TLS connection can not be established, Mailgun will not deliver the message.If set to False, Mailgun will still try and upgrade the connection, but if Mailgun can not, the message will be delivered over a plaintext SMTP connection. The default is False.
skipVerification	If set to True, the certificate and hostname will not be verified when trying to establish a TLS connection and Mailgun will accept any certificate during delivery. If set to False, Mailgun will verify the certificate and hostname. If either one can not be verified, a TLS connection will not be established. The default is False.

Stats

Get Domain Stats - GET /[domain]/stats

mailGun.getStats([options, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function takes an optional options argument that will take an object or a string and use it as a search query. The query options are listed here. If a string is passed, it should be in the format of var1=val1&var2=val2.

Delete Domain Stats - GET /[domain]/stats

mailGun.deleteStats(tagName[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

When a tag is applied to an email set, it is recorded by MailGun. This function removes those custom counts. As far as I know, you can't remove the system ones like 'sent'. Though, then again, I never tried...

Events

Retrieving Events - GET /[domain]/events

mailGun.getEvents([options, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This endpoint is somewhat confusing. Please re-read all of this twice before sending angry emails or help make it less confusing. Please first understand the limits on logging for Mailgun domains. For Free accounts you will only be able to see the last two days of logs. For paid accounts, you will be able to see the last 30.

With that in mind, let us explore the search option. The same as above, you can either pass the search option as an object or as a string in 'var1=val1' format.

** Date ranges only work if you specify (BOTH 'begin' and 'end') OR (either 'begin' or 'end' AND 'ascending') **

In addition to 'begin', 'end', and 'ascending', any field from the query options can be passed as key/value pairs in the search object.

Currently, this function does not support event polling as suggested by the Mailgun docs.

Suppressions

Get Bounces - GET /[domain]/bounces/[address]

mailGun.getBounces([search, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

When emails are bounced back from a server with a fatal error message, Mailgun does the good guy thing and black lists them for you automatically. This endpoint will return a list the addresses that Mailgun as on your bounce list, along with the reason it is on the list (if it was assigned when the bounce record was created).

Add Bounces - POST /[domain]/bounces

mailGun.addBounces({
    "address": "alice@example.com",
    "code": "550",
    "error": "Bounced",
    "created_at": "Thu, 13 Oct 2011 18:02:00 UTC"
  }[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

Mailgun allows you to batch create bounce lists or to create single records. As far as required fields, the only key:value you need to have in the object is the address. You can either pass a single object to this function or an array of objects up to 1000 at a time.

Delete Bounces - DELETE /[domain]/bounces

mailGun.deleteBounces(address[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes email address from the bounce list. Be careful when doing this. There may be a good reason why the email in on this list.

Get Unsubscribes - GET /[domain]/unsubscribes/[addres]

mailGun.getUnsubscribes([search, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function returns the unsubscribes for the specified domain. If an address is given, it will return data about that single email.

Add Unsubscribes - POST /[domain]/unsubscribes

mailGun.addUnsubscribes({
    "address": "alice@example.com",
    "tag": "Tag to unsubscribe from.",
    "created_at": "Thu, 13 Oct 2011 18:02:00 UTC"
  }[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

When adding an email to be unsubscribed, you may specify a tag to unsubscribe from. Also, and the default, '*' will unsubscribe from all mailings.

Delete Unsubscribes - DELETE /[domain]/unsubscribes

mailGun.deleteUnsubscribes(address[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes an email from the domain unsubscribe list. Be careful, there may be a good reason why the email in on this list.

Get Complaints - GET /[domain]/complaints/[addres]

mailGun.getComplaints([search, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function returns the complaints for the specified domain. If an address is given, it will return data about that single email.

Add Complaints - POST /[domain]/complaints

mailGun.addComplaints({
    "address": "alice@example.com",
    "created_at": "Thu, 13 Oct 2011 18:02:00 UTC"
  }[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

Manually adds a complaining address to the complaint list.

Delete Complaints - DELETE /[domain]/complaints

mailGun.deleteComplaints(address[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes an email from the domain complaint list. Be careful, there may be a good reason why the email in on this list.

Routes

Get Routes - GET /routes/[id]

mailGun.getRoutes([id, limit, skip]);

Returns

promise(MailGun_Response, Rejection_Message)

This function returns either 1) A list of routes when limit, skip, both, or no arguments are passed or 2) one record when id is given as they are unique.

Add Routes - POST /routes

mailGun.addRoutes({
    "priority": 10,
    "description": "Any kind of helpful text you wish to remind yourself",
    "expression": "The [filter](https://documentation.mailgun.com/user_manual.html#routes) for the route",
    "action": "The [action](https://documentation.mailgun.com/user_manual.html#routes) for a true filter"
  });

Returns

promise(MailGun_Response, Rejection_Message)

This function adds a route record to the account. The filters that Mailgun should be first read about in the official docs before trying to be used. They are extremely robust and offer many options. Currently, this function only lets you associate one action with each route.

Update Routes - PUT /routes

mailGun.updateRoutes(routeId, {
    "priority": Number,
    "description": "Any kind of helpful text you wish to remind yourself",
    "expression": "The [filter](https://documentation.mailgun.com/user_manual.html#routes) for the route",
    "action": "The [action](https://documentation.mailgun.com/user_manual.html#routes) for a true filter"
  });

Returns

promise(MailGun_Response, Rejection_Message)

This function updates the route with the specified routeId. From the object in the second parameter, only one field is required and it does not matter which field is passed. If you do not want to change a field, just don't include it.

Delete Routes - DELETE /routes

mailGun.deleteRoutes(routeId);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes a route from the domain list.

Campaigns

Get Campaigns - GET /[domain]/campaigns

mailGun.getCampaigns([id, limit, skip, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

While designing this function, I ran into a small problem: trying to use tests to determine if id is passed or if it was just the limit. To solve this, id must be passed as a string and limit must be passed as a number. If limit is passed as a string, no type conversion will happen, and you're only going to get one result back. That single result will be the search results for the campaign id.

Add Campaigns - POST /[domain]/campaigns

mailGun.addCampaigns(campaign[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This will add a new campaign tag to the server to track. Campaign should be an object with a 'name' and an 'id.'

Update Campaigns - PUT /[domain]/campaigns/[id]

mailGun.updateCampaigns(id, newData[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

Currently this function only has the ability to change the name of the campaign. Stay tuned for the ability to also change the id.

Delete Campaigns - DELETE /[domain]/campaigns/[id]

mailGun.deleteCampaigns(idToDelete, domain);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes a campaign from the domain list. It also deletes all associated data for the campaign.

Get Campaign Events - GET /[domain]/campaigns/[id]/[eventType]

mailGun.getCampaignsEvents(campId[, eventType, options, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function retrieves information about a certain campaign. Make sure you read the official docs about the ways you can sort this information. Any key can be passed into the options object. (e.g., {recipient: 'bob@mail.com' } The accepted eventType's are:

events - returns all of the following events
stats - returns a summary of the campaign events
clicks - returns data about what is clicked in the email
opens - returns data about the number of emails that were actually opened
unsubscribes - returns data about the number of unsubscribes
complaints - returns data about the complaints the campaign has received

Webhooks

Get Webhooks - GET /domains/[domain]/webhooks/[webhookname]

mailGun.getWebhooks([hookName, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function will return a list of webhooks for specified domain. hookName refers to the event type and is discussed below under Add Webhooks.

Add Webhooks - POST /domains/[domain]/webhooks

mailGun.addWebhooks(hookName, url[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function creates a webhook for the named domain. 'hookName' is the name used by Mailgun. They call it 'id' but I think that it should really be called 'type' as this is the field that triggers the webhook. The possible options are below. 'url' refers to the url called by the webhook.

bounce
deliver
drop
spam
unsubscribe
click
open

Update Webhooks - PUT /domains/[domain]/webhooks/[webhookname]

mailGun.updateWebhooks(id, url[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

Since 'id' refers to the hook type, both id and url are required for this function.

Delete Webhooks - DELETE /domains/[domain]/webhooks/[webhookname]

mailGun.deleteWebhooks(idToDelete[, domain]);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes a webhook from the domain list.

Verify Webhook - Webhook Security

mailGun.verifyWebhook(timestamp, token, signature)

Returns

promise(Webhook_Verified, Webhook_Suspicious)

This function verifies a call from Mailgun to your webhook service. The timestamp, token, and signature are located in the headers sent to the webhook service. In addition, this also requires you to have your private API key set as the key is used in the hashing of the signature.

Mailing Lists

Get Mailing Lists - GET /lists/[address]

mailGun.getMailLists([listName]);

Returns

promise(MailGun_Response, Rejection_Message)

This function will return a list of mailing lists for all domains. Currently MailGun does not have a method of searching/filtering by domain.

Add Mailing List - POST /lists/[address]

mailGun.addMailLists(listData);

Returns

promise(MailGun_Response, Rejection_Message)

This function will create a new mailing list. listData should include:

address - The email address that you will send email to that will distribute to all members.
name - Name of the mailing list
description - A description of the mailing list to remind you of what it is
accessLevel - One of the following: readonly, members, everyone. See the Mailgun Docs for more information on these options.

Update Mailing List - PUT /lists/[address]

mailGun.updateMailLists(addressList, listData);

Returns

promise(MailGun_Response, Rejection_Message)

Updates given mailing list (address).

Delete Mailing Address - DELETE /lists/[address]

mailGun.deleteMailLists(idToDelete);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes a mailing list.

Get Mailing List Members - GET /lists/[address]/members/[member_address]

mailGun.getMailListsMembers(listName[, memberName]);

Returns

promise(MailGun_Response, Rejection_Message)

This function allows you to dig deeper into your mail list subscribers. If a member email address is given, information about that user will be sent back. If not, all members of the mailing list will be returned.

Add Mailing List Members- POST /lists/[address]/members

mailGun.addMailListsMembers(listAddress, memberObject[, upsert]);

Returns

promise(MailGun_Response, Rejection_Message)

This function will create a new mailing list member. Member object can be an object or an array of objects. These objects shoud include:

address - The email to add.
name - The member name
vars - A arbitrary JSON object that holds user data with the record
subscribed - yes (default) to add as a mail receiving member.

Update Mailing List Member - PUT /lists/[address]/members/[member_address]

mailGun.updateMailListsMembers(listAddress, memberAddress, memberObject);

Returns

promise(MailGun_Response, Rejection_Message)

Updates a single mailing list member (address).

Delete Mailing Address Member - DELETE /lists/[address]/members/[member_address]

mailGun.deleteMailListsMembers(listAddress, memberAddress);

Returns

promise(MailGun_Response, Rejection_Message)

This function removes a mailing list member.

Email Validation

Check if Email is Valid - GET /address/vaidate

mailGun.validateEmail(emailToCheck);

Returns

promise(MailGun_Response, Rejection_Message)

This function checks to see if a email appears to be valid. See Mailgun docs for what checks it performs. Also, this function uses the public API key, as opposed to the private one.

Parse Email Address - GET /address/parse

mailGun.parseEmail(emailToParse[, syntaxOnly]);

Returns

promise(MailGun_Response, Rejection_Message)

This function takes an email address and returns the parts. For more information, see the Mailgun docs. This function also uses the Public API key.