README
¶
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("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
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 :)
Documentation
¶
Overview ¶
Package sendgrid provides a simple interface to interact with the SendGrid API
Index ¶
- Constants
- type SGClient
- type SGMail
- func (m *SGMail) AddAttachment(filename string, file io.Reader) error
- func (m *SGMail) AddAttachmentFromStream(filename, file string)
- func (m *SGMail) AddBcc(bcc string) error
- func (m *SGMail) AddBccRecipient(recipient *mail.Address)
- func (m *SGMail) AddBccRecipients(recipients []*mail.Address)
- func (m *SGMail) AddBccs(bccs []string) error
- func (m *SGMail) AddCc(cc string) error
- func (m *SGMail) AddCcRecipient(recipient *mail.Address)
- func (m *SGMail) AddCcRecipients(recipients []*mail.Address)
- func (m *SGMail) AddCcs(ccs []string) error
- func (m *SGMail) AddContentID(id, value string)
- func (m *SGMail) AddHeader(header, value string)
- func (m *SGMail) AddRecipient(recipient *mail.Address)
- func (m *SGMail) AddRecipients(recipients []*mail.Address)
- func (m *SGMail) AddTo(email string) error
- func (m *SGMail) AddToName(name string)
- func (m *SGMail) AddToNames(names []string)
- func (m *SGMail) AddTos(emails []string) error
- func (m *SGMail) HeadersString() (string, error)
- func (m *SGMail) SetDate(date string)
- func (m *SGMail) SetFrom(from string) error
- func (m *SGMail) SetFromEmail(address *mail.Address)
- func (m *SGMail) SetFromName(fromname string)
- func (m *SGMail) SetHTML(html string)
- func (m *SGMail) SetRFCDate(date time.Time)
- func (m *SGMail) SetReplyTo(replyto string) error
- func (m *SGMail) SetReplyToEmail(address *mail.Address)
- func (m *SGMail) SetSubject(subject string)
- func (m *SGMail) SetText(text string)
Constants ¶
const Version = "2.0.0"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type SGClient ¶
type SGClient struct {
APIMail string
Client *http.Client
// contains filtered or unexported fields
}
SGClient will contain the credentials and default values
func NewSendGridClient ¶
NewSendGridClient will return a new SGClient. Used for username and password
func NewSendGridClientWithApiKey ¶
NewSendGridClient will return a new SGClient. Used for api key
type SGMail ¶
type SGMail struct {
To []string
ToName []string
Cc []string
Subject string
Text string
HTML string
From string
Bcc []string
FromName string
ReplyTo string
Date string
Files map[string]string
Content map[string]string
Headers map[string]string
smtpapi.SMTPAPIHeader
}
SGMail is representation of a valid SendGrid Mail
func (*SGMail) AddAttachment ¶
AddAttachment allows file attachments to be sent. For security reasons, this method doesn't take filepaths only the io.Reader interface.
func (*SGMail) AddAttachmentFromStream ¶
AddAttachmentFromStream ...
func (*SGMail) AddBccRecipient ¶
AddBccRecipient ...
func (*SGMail) AddBccRecipients ¶
AddBccRecipients ...
func (*SGMail) AddCcRecipient ¶
AddCcRecipient ...
func (*SGMail) AddCcRecipients ¶
AddCcRecipients ...
func (*SGMail) AddRecipient ¶
AddRecipient will add mail.Address emails to recipients.
func (*SGMail) AddRecipients ¶
AddRecipients calls AddRecipient per email
func (*SGMail) AddToNames ¶
AddToNames sets the "pretty" name for multiple recipients
func (*SGMail) HeadersString ¶
func (*SGMail) SetFromEmail ¶
SetFromEmail sets the senders email property
func (*SGMail) SetReplyToEmail ¶
SetReplyToEmail ...
func (*SGMail) SetSubject ¶
SetSubject sets the email's subject
Source Files