mailgunUser Guide

Overview

Mailgun is a simple Fantom API wrapper for the Mailgun email service.

Usage

mailgun := Mailgun
{
  it.privApiKey = "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"
  it.pubApiKey = "pubkey-aba038xlkaj444a898akjzlsoo"
  it.domain = "samples.mailgun.org"
}

Sending

See full send documentation.

mailgun.send([
  "from": "me@samples.mailgun.org",
  "to": "alex@mailgun.net, ev@mailgun.net",
  "subject": "Hey There!",
  "text": "Hi :)"
])

Or use an Email instance:

email := Email
{
  from = "me@samples.mailgun.org"
  to = ["alex@mailgun.net, ev@mailgun.net"]
  subject = "Hey There!"
  body = TextPart { text = "Hi :)" }
}
mailgun.sendEmail(email)

Unsubscribes

See full documentation.

mailgun.unsubscribe                            // get unsubscribe table
mailgun.addUnsubscribe("alex@mailgun.net")     // add address to unsub table
mailgun.getUnsubscribe("alex@mailgun.net")     // get all unsub entries for address
mailgun.removeUnsubscribe("alex@mailgun.net")  // remove all unsub entries for address

// add with tags
mailgun.addUnsubscribe("alex@mailgun.net", "someTag")

Spam Complaints

See full documentation.

mailgun.complaints                           // get complaints table
mailgun.addComplaint("alex@mailgun.net")     // add address to complaints table
mailgun.getComplaint("alex@mailgun.net")     // get complaints entry for address
mailgun.removeComplaint("alex@mailgun.net")  // remove address from complaints table

Bounces

See full documentation.

mailgun.bounces                           // get bounces table
mailgun.addBounce("alex@mailgun.net")     // add address to bounce table
mailgun.getBounce("alex@mailgun.net")     // get bounce entry for address
mailgun.removeBounce("alex@mailgun.net")  // remove address from bounce table

// add with specific error code and message
mailgun.addBounce("alex@mailgun.net", 551, "The recipient is not local to the server.")

Events

See full documentation

mailgun.events(...)  // retrieve events for given params

// get list of all delivered events on the day of 2017-07-01
mailgun.events(["event":"delivered"], Date(2017-07-01), Date(2017-07-01))

Note that events in particular may be paged. See Paging for more details on iterating paged results.

Email Validation

Email validation requires a pubApiKey to be configured. See full validation documentation.

mailgun.isValidAddres("foo@acme.com")     // true or false
mailgun.validateAddress("foo@acme.com")   // get full Mailgun validation response as a map

Paging

Certain API calls return "pages" of results. For example, the events API works by returning pages of events. Paging information is only available in the first and last entry of the item list. You can page through results by passing either the first or last item to one of the following methods:

Example:

// request the initial page of events
events := mailgun.events(["event":"delivered"], Date(2017-07-01), Date(2017-07-01))

// loop until current event list is empty
while (!events.isEmpty)
{
  events.each |event| { ... }              // process event
  events = mailgun.pageNext(events.last)   // retrieve next page
}

Everything Else

Not every API has first-class support yet. And just in case Mailgun adds new APIs that are't yet implemented here, you can drop down and use the invoke method to directly access Mailgun's REST API:

// both lines are equivalent
mailgun.log(25)
mailgun.invoke("GET", `/log`, ["limit":"25"])

The return type for invoke will either be a Str:Obj or it will be a [Str:Obj][] list. Refer to the Mailgun documentation on expected result.