Need help with mailgun-go?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

mailgun
487 Stars 107 Forks BSD 3-Clause "New" or "Revised" License 480 Commits 6 Opened issues

Description

Go library for sending mail with the Mailgun API.

Services available

!
?

Need anything else?

Contributors list

No Data

Mailgun with Go

GoDoc Build Status

Go library for interacting with the Mailgun API.

Usage

package main

import ( "context" "fmt" "log" "time"

"github.com/mailgun/mailgun-go/v4"

)

// Your available domain names can be found here: // (https://app.mailgun.com/app/domains) var yourDomain string = "your-domain-name" // e.g. mg.yourcompany.com

// You can find the Private API Key in your Account Menu, under "Settings": // (https://app.mailgun.com/app/account/security) var privateAPIKey string = "your-private-key"

func main() { // Create an instance of the Mailgun Client mg := mailgun.NewMailgun(yourDomain, privateAPIKey)

sender := "[email protected]"
subject := "Fancy subject!"
body := "Hello from Mailgun Go!"
recipient := "[email protected]"

// The message object allows you to add attachments and Bcc recipients
message := mg.NewMessage(sender, subject, body, recipient)

ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
defer cancel()

// Send the message with a 10 second timeout
resp, id, err := mg.Send(ctx, message)

if err != nil {
    log.Fatal(err)
}

fmt.Printf("ID: %s Resp: %s\n", id, resp)

}

Get Events

package main

import ( "context" "fmt" "time"

"github.com/mailgun/mailgun-go/v4"
"github.com/mailgun/mailgun-go/v4/events"

)

func main() { // You can find the Private API Key in your Account Menu, under "Settings": // (https://app.mailgun.com/app/account/security) mg := mailgun.NewMailgun("your-domain.com", "your-private-key")

it := mg.ListEvents(&mailgun.ListEventOptions{Limit: 100})

var page []mailgun.Event

// The entire operation should not take longer than 30 seconds
ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
defer cancel()

// For each page of 100 events
for it.Next(ctx, &page) {
    for _, e := range page {
        // You can access some fields via the interface
        fmt.Printf("Event: '%s' TimeStamp: '%s'\n", e.GetName(), e.GetTimestamp())

        // and you can act upon each event by type
        switch event := e.(type) {
        case *events.Accepted:
            fmt.Printf("Accepted: auth: %t\n", event.Flags.IsAuthenticated)
        case *events.Delivered:
            fmt.Printf("Delivered transport: %s\n", event.Envelope.Transport)
        case *events.Failed:
            fmt.Printf("Failed reason: %s\n", event.Reason)
        case *events.Clicked:
            fmt.Printf("Clicked GeoLocation: %s\n", event.GeoLocation.Country)
        case *events.Opened:
            fmt.Printf("Opened GeoLocation: %s\n", event.GeoLocation.Country)
        case *events.Rejected:
            fmt.Printf("Rejected reason: %s\n", event.Reject.Reason)
        case *events.Stored:
            fmt.Printf("Stored URL: %s\n", event.Storage.URL)
        case *events.Unsubscribed:
            fmt.Printf("Unsubscribed client OS: %s\n", event.ClientInfo.ClientOS)
        }
    }
}

}

Event Polling

The mailgun library has built-in support for polling the events api ```go package main

import ( "context" "time"

"github.com/mailgun/mailgun-go/v4"

)

func main() { // You can find the Private API Key in your Account Menu, under "Settings": // (https://app.mailgun.com/app/account/security) mg := mailgun.NewMailgun("your-domain.com", "your-private-key")

begin := time.Now().Add(time.Second * -3)

// Very short poll interval it := mg.PollEvents(&mailgun.ListEventOptions{ // Only events with a timestamp after this date/time will be returned Begin: &begin, // How often we poll the api for new events PollInterval: time.Second * 30, })

ctx, cancel := context.WithCancel(context.Background()) defer cancel()

// Poll until our email event arrives var page []mailgun.Event for it.Poll(ctx, &page) { for _, e := range page { // Do something with event } }

} ```

Email Validations

package main

import ( "context" "fmt" "log" "time"

"github.com/mailgun/mailgun-go/v4"

)

// If your plan does not include email validations but you have an account, // use your Public Validation api key. If your plan does include email validations, // use your Private API key. You can find both the Private and // Public Validation API Keys in your Account Menu, under "Settings": // (https://app.mailgun.com/app/account/security) var apiKey string = "your-api-key"

func main() { // To use the /v4 version of validations define MG_URL in the environment // as https://api.mailgun.net/v4 or set v.SetAPIBase("https://api.mailgun.net/v4")

// Create an instance of the Validator
v := mailgun.NewEmailValidator(apiKey)

ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
defer cancel()

email, err := v.ValidateEmail(ctx, "[email protected]", false)
if err != nil {
    panic(err)
}
fmt.Printf("Valid: %t\n", email.IsValid)

}

Webhook Handling

package main

import ( "context" "encoding/json" "fmt" "net/http" "os" "time"

"github.com/mailgun/mailgun-go/v4"
"github.com/mailgun/mailgun-go/v4/events"

)

func main() {

// You can find the Private API Key in your Account Menu, under "Settings":
// (https://app.mailgun.com/app/account/security)
mg := mailgun.NewMailgun("your-domain.com", "private-api-key")

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {

    var payload mailgun.WebhookPayload
    if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
        fmt.Printf("decode JSON error: %s", err)
        w.WriteHeader(http.StatusNotAcceptable)
        return
    }

    verified, err := mg.VerifyWebhookSignature(payload.Signature)
    if err != nil {
        fmt.Printf("verify error: %s\n", err)
        w.WriteHeader(http.StatusNotAcceptable)
        return
    }

    if !verified {
        w.WriteHeader(http.StatusNotAcceptable)
        fmt.Printf("failed verification %+v\n", payload.Signature)
        return
    }

    fmt.Printf("Verified Signature\n")

    // Parse the event provided by the webhook payload
    e, err := mailgun.ParseEvent(payload.EventData)
    if err != nil {
        fmt.Printf("parse event error: %s\n", err)
        return
    }

    switch event := e.(type) {
    case *events.Accepted:
        fmt.Printf("Accepted: auth: %t\n", event.Flags.IsAuthenticated)
    case *events.Delivered:
        fmt.Printf("Delivered transport: %s\n", event.Envelope.Transport)
    }
})

fmt.Println("Serve on :9090...")
if err := http.ListenAndServe(":9090", nil); err != nil {
    fmt.Printf("serve error: %s\n", err)
    os.Exit(1)
}

}

Using Templates

Templates enable you to create message templates on your Mailgun account and then populate the data variables at send-time. This allows you to have your layout and design managed on the server and handle the data on the client. The template variables are added as a JSON stringified

X-Mailgun-Variables
header. For example, if you have a template to send a password reset link, you could do the following:
package main

import ( "context" "fmt" "log" "time"

"github.com/mailgun/mailgun-go/v4"

)

// Your available domain names can be found here: // (https://app.mailgun.com/app/domains) var yourDomain string = "your-domain-name" // e.g. mg.yourcompany.com

// You can find the Private API Key in your Account Menu, under "Settings": // (https://app.mailgun.com/app/account/security) var privateAPIKey string = "your-private-key"

func main() { // Create an instance of the Mailgun Client mg := mailgun.NewMailgun(yourDomain, privateAPIKey)

sender := "[email protected]"
subject := "Fancy subject!"
body := ""
recipient := "[email protected]"

// The message object allows you to add attachments and Bcc recipients
    message := mg.NewMessage(sender, subject, body, recipient)
    message.SetTemplate("passwordReset")
    message.AddTemplateVariable("passwordResetLink", "some link to your site unique to your user")

ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
defer cancel()

// Send the message with a 10 second timeout
resp, id, err := mg.Send(ctx, message)

if err != nil {
    log.Fatal(err)
}

fmt.Printf("ID: %s Resp: %s\n", id, resp)

}

The official mailgun documentation includes examples using this library. Go here and click on the "Go" button at the top of the page.

EU Region

European customers will need to change the default API Base to access your domains

mg := mailgun.NewMailgun("your-domain.com", "private-api-key")
mg.SetAPIBase(mailgun.APIBaseEU)

Installation

If you are using golang modules make sure you include the

/v4
at the end of your import paths
bash
$ go get github.com/mailgun/mailgun-go/v4

If you are not using golang modules, you can drop the

/v4
at the end of the import path. As long as you are using the latest 1.10 or 1.11 golang release, import paths that end in
/v4
in your code should work fine even if you do not have golang modules enabled for your project.
bash
$ go get github.com/mailgun/mailgun-go

NOTE for go dep users

Using version 3 of the mailgun-go library with go dep currently results in the following error

"github.com/mailgun/mailgun-go/v4/events", which contains malformed code: no package exists at ...
This is a known bug in go dep. You can follow the PR to fix this bug here Until this bug is fixed, the best way to use version 3 of the mailgun-go library is to use the golang community supported golang modules.

Testing

WARNING - running the tests will cost you money!

To run the tests various environment variables must be set. These are:

  • MG_DOMAIN
    is the domain name - this is a value registered in the Mailgun admin interface.
  • MG_PUBLIC_API_KEY
    is the Public Validation API key - you can get this value from the Mailgun security page
  • MG_API_KEY
    is the Private API key - you can get this value from the Mailgun security page
  • MG_EMAIL_TO
    is the email address used in various sending tests.

and finally

  • MG_SPEND_MONEY
    if this value is set the part of the test that use the API to actually send email will be run - be aware this will count on your quota and this will cost you money.

The code is released under a 3-clause BSD license. See the LICENSE file for more information.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.