Skip to content

Latest commit

 

History

History
251 lines (189 loc) · 5.82 KB

README.md

File metadata and controls

251 lines (189 loc) · 5.82 KB
Raw

SendGrid-Go

GoDoc Visit the GoDoc.

Build Status 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("yamil@sendgrid.com")
	message.AddToName("Yamil Asusta")
	message.SetSubject("SendGrid Testing")
	message.SetText("WIN")
	message.SetFrom("yamil@sendgrid.com")
    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("example@sendgrid.com") // Returns error if email string is not valid RFC 5322
// or
address, _ := mail.ParseAddress("Example <example@sendgrid.com>")
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("example@lol.com")

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("addTo@mailinator.com")
// or
tos := []string{"test@test.com", "test@email.com"}
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)

Category

message.AddCategory("category")
// or
categories := []string{"setCategories"}
message.AddCategories(categories)
// or
message.SetCategories(categories)

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

Send emails through a proxy

Cloud deployment platforms such as Heroku do not guarantee a static IP. Hence it is advisable to use proxies form static outbound IP services. Use SendThroughProxy() to do so:

proxyURL := "http://user:passwd@proxyserver.xyz:port"
if e := client.SendThroughProxy(m, proxyURL); e != nil {
   t.Errorf("Send failed to send email through proxy. Returned error: %v", e)
}

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("yamil@sendgrid.com")
	message.SetSubject("SendGrid is Baller")
	message.SetHTML("Simple Text")
	message.SetFrom("kunal@sendgrid.com")
	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 :)