SendGrid-Go

Visit the GoDoc.

SendGrid Helper Library to send emails very easily using Go.

Warning

Version 2.x.x drops support for Go versions < 1.3.

Version 1.2.x behaves differently in the AddTo method. In the past this method defaulted to using the SMTPAPI header. Now you must explicitly call the SMTPAPIHeader.AddTo method. More on the SMTPAPI section.

Installation

go get github.com/sendgrid/sendgrid-go

// Or pin the version with gopkg
go get gopkg.in/sendgrid/sendgrid-go.v1

Example

package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
)

func main() {
	sg := sendgrid.NewSendGridClient("sendgrid_user", "sendgrid_key")
	message := sendgrid.NewMail()
	message.AddTo("[email protected]")
	message.AddToName("Yamil Asusta")
	message.SetSubject("SendGrid Testing")
	message.SetText("WIN")
	message.SetFrom("[email protected]")
    if r := sg.Send(message); r == nil {
		fmt.Println("Email sent!")
	} else {
		fmt.Println(r)
	}
}

Usage

To begin using this library, call NewSendGridClient with your SendGrid credentials OR NewSendGridClientWithApiKey with a SendGrid API Key. API Key is the preferred method. API Keys are in beta. To configure API keys, visit https://sendgrid.com/beta/settings/api_key.

Creating a Client

sg := sendgrid.NewSendGridClient("sendgrid_user", "sendgrid_key")
// or
sg := sendgrid.NewSendGridClientWithApiKey("sendgrid_api_key")

Creating a Mail

message := sendgrid.NewMail()

Adding Recipients

message.AddTo("[email protected]") // Returns error if email string is not valid RFC 5322
// or
address, _ := mail.ParseAddress("Example <[email protected]>")
message.AddRecipient(address) // Receives a vaild mail.Address

Adding BCC Recipients

Same concept as regular recipient excepts the methods are:

AddBcc
AddBccRecipient

Setting the Subject

message.SetSubject("New email")

Set Text or HTML

message.SetText("Add Text Here..")
//or
message.SetHTML("<html><body>Stuff, you know?</body></html>")

Set From

message.SetFrom("[email protected]")

Set File Attachments

message.AddAttachment("text.txt", file) // file needs to implement the io.Reader interface
//or
message.AddAttachmentFromStream("filename", "some file content")

Adding ContentIDs

message.AddContentID("id", "content")

SendGrid's X-SMTPAPI

If you wish to use the X-SMTPAPI on your own app, you can use the SMTPAPI Go library.

Recipients

message.SMTPAPIHeader.AddTo("[email protected]")
// or
tos := []string{"[email protected]", "[email protected]"}
message.SMTPAPIHeader.AddTos(tos)
// or
message.SMTPAPIHeader.SetTos(tos)

Substitutions

message.AddSubstitution("key", "value")
// or
values := []string{"value1", "value2"}
message.AddSubstitutions("key", values)
//or
sub := make(map[string][]string)
sub["key"] = values
message.SetSubstitutions(sub)

Section

message.AddSection("section", "value")
// or
sections := make(map[string]string)
sections["section"] = "value"
message.SetSections(sections)

Unique Arguments

message.AddUniqueArg("key", "value")
// or
args := make(map[string]string)
args["key"] = "value"
message.SetUniqueArgs(args)

Filters

message.AddFilter("filter", "setting", "value")
// or
filter := &Filter{
  Settings: make(map[string]string),
}
filter.Settings["enable"] = "1"
filter.Settings["text/plain"] = "You can haz footers!"
message.SetFilter("footer", filter)

JSONString

message.JSONString() //returns a JSON string representation of the headers

AppEngine Example

package main

import (
	"fmt"
	"appengine/urlfetch"
	"github.com/sendgrid/sendgrid-go"
)

func handler(w http.ResponseWriter, r *http.Request) {
	sg := sendgrid.NewSendGridClient("sendgrid_user", "sendgrid_key")
	c := appengine.NewContext(r)
	// set http.Client to use the appengine client
	sg.Client = urlfetch.Client(c) //Just perform this swap, and you are good to go.
	message := sendgrid.NewMail()
	message.AddTo("[email protected]")
	message.SetSubject("SendGrid is Baller")
	message.SetHTML("Simple Text")
	message.SetFrom("[email protected]")
	if r := sg.Send(message); r == nil {
		fmt.Println("Email sent!")
	} else {
		c.Errorf("Unable to send mail %v",r)
	}
}

Kudos to Matthew Zimmerman for this example.

###Tests

Please run the test suite in before sending a pull request.

go test -v

TODO:

Add Versioning
Add proper support for BCC

##MIT License

Enjoy. Feel free to make pull requests :)

mzimmerman / sendgrid-go Goto Github PK

sendgrid-go's Introduction