You've already forked openaccounting-server
mirror of
https://github.com/openaccounting/oa-server.git
synced 2025-12-09 00:50:59 +13:00
mailgun dep
This commit is contained in:
Patrick Nagurny
363
vendor/github.com/mailgun/mailgun-go/v4/README.md
generated
vendored
Normal file
363
vendor/github.com/mailgun/mailgun-go/v4/README.md
generated
vendored
Normal file
@@ -0,0 +1,363 @@
|
||||
# Mailgun with Go
|
||||
|
||||
[](https://godoc.org/github.com/mailgun/mailgun-go)
|
||||
[](https://travis-ci.org/mailgun/mailgun-go)
|
||||
|
||||
Go library for interacting with the [Mailgun](https://mailgun.com/) [API](https://documentation.mailgun.com/api_reference.html).
|
||||
|
||||
## Usage
|
||||
```go
|
||||
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 := "sender@example.com"
|
||||
subject := "Fancy subject!"
|
||||
body := "Hello from Mailgun Go!"
|
||||
recipient := "recipient@example.com"
|
||||
|
||||
// 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
|
||||
```go
|
||||
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
|
||||
```go
|
||||
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, "recipient@example.com", false)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
fmt.Printf("Valid: %t\n", email.IsValid)
|
||||
}
|
||||
```
|
||||
|
||||
## Webhook Handling
|
||||
```go
|
||||
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:
|
||||
|
||||
```go
|
||||
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 := "sender@example.com"
|
||||
subject := "Fancy subject!"
|
||||
body := ""
|
||||
recipient := "recipient@example.com"
|
||||
|
||||
// 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](https://documentation.mailgun.com/en/latest/api_reference.html#api-reference)
|
||||
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
|
||||
|
||||
```go
|
||||
mg := mailgun.NewMailgun("your-domain.com", "private-api-key")
|
||||
mg.SetAPIBase(mailgun.APIBaseEU)
|
||||
```
|
||||
## Installation
|
||||
|
||||
If you are using [golang modules](https://github.com/golang/go/wiki/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](https://github.com/golang/dep/pull/1963)
|
||||
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](https://github.com/golang/go/wiki/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](https://app.mailgun.com/app/account/security)
|
||||
* `MG_API_KEY` is the Private API key - you can get this value from the Mailgun [security page](https://app.mailgun.com/app/account/security)
|
||||
* `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.
|
||||
Reference in New Issue
Block a user