mail

README

github.com/thegodwinproject/buffalo/mail

This package is intended to allow easy Email sending with Buffalo, it allows you to define your custom mail.Sender for the provider you would like to use.

Generator

buffalo generate mailer welcome_email

Example Usage

//actions/mail.go
package x

import (
    "log"
    "net/http"

    "github.com/thegodwinproject/buffalo/render"
    "github.com/gobuffalo/envy"
    "github.com/gobuffalo/plush"
    "github.com/thegodwinproject/buffalo/mail"
    "errors"
    "gitlab.com/wawandco/app/models"
)

var smtp mail.Sender
var r *render.Engine

func init() {

    //Pulling config from the env.
    port := envy.Get("SMTP_PORT", "1025")
    host := envy.Get("SMTP_HOST", "localhost")
    user := envy.Get("SMTP_USER", "")
    password := envy.Get("SMTP_PASSWORD", "")

    var err error
    smtp, err = mail.NewSMTPSender(host, port, user, password)

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

    //The rendering engine, this is usually generated inside actions/render.go in your buffalo app.
    r = render.New(render.Options{
        TemplatesFS:   mailTemplates,
    })
}

//SendContactMessage Sends contact message to contact@myapp.com
func SendContactMessage(c *models.Contact) error {

    //Creates a new message
    m := mail.NewMessage()
    m.From = "sender@myapp.com"
    m.Subject = "New Contact"
    m.To = []string{"contact@myapp.com"}

    // Data that will be used inside the templates when rendering.
    data := map[string]interface{}{
        "contact": c,
    }

    // You can add multiple bodies to the message you're creating to have content-types alternatives.
    err := m.AddBodies(data, r.HTML("mail/contact.html"), r.Plain("mail/contact.txt"))

    if err != nil {
        return err
    }

    err = smtp.Send(m)
    if err != nil {
        return err
    }

    return nil
}

This SendContactMessage could be called by one of your actions, p.e. the action that handles your contact form submission.

//actions/contact.go
...

func ContactFormHandler(c buffalo.Context) error {
    contact := &models.Contact{}
    c.Bind(contact)

    //Calling to send the message
    SendContactMessage(contact)
    return c.Redirect(http.StatusFound, "contact/thanks")
}
...

If you're using Gmail or need to configure your SMTP connection you can use the Dialer property on the SMTPSender, p.e: (for Gmail)

...
var smtp mail.Sender

func init() {
    port := envy.Get("SMTP_PORT", "465")
    // or 587 with TLS

    host := envy.Get("SMTP_HOST", "smtp.gmail.com")
    user := envy.Get("SMTP_USER", "your@email.com")
    password := envy.Get("SMTP_PASSWORD", "yourp4ssw0rd")

    var err error
    sender, err := mail.NewSMTPSender(host, port, user, password)
    sender.Dialer.SSL = true

    //or if TLS
    sender.Dialer.TLSConfig = &tls.Config{...}

    smtp = sender
}
...

Documentation

Index

• type Attachment
• type BatchSender
• type Body
• type Message
  • func New(c buffalo.Context) Message
  • func NewFromData(data render.Data) Message
  • func NewMessage() Message
  • func (m *Message) AddAttachment(name, contentType string, r io.Reader) error
  • func (m *Message) AddBodies(data render.Data, renderers ...render.Renderer) error
  • func (m *Message) AddBody(r render.Renderer, data render.Data) error
  • func (m *Message) AddEmbedded(name string, r io.Reader) error
  • func (m *Message) SetHeader(field, value string)
• type SMTPSender
  • func NewSMTPSender(host string, port string, user string, password string) (SMTPSender, error)
  • func (sm SMTPSender) Send(message Message) error
  • func (sm SMTPSender) SendBatch(messages ...Message) (errorsByMessages []error, generalError error)
• type Sender

Types

type Attachment

type Attachment struct {
	Name        string
	Reader      io.Reader
	ContentType string
	Embedded    bool
}

Attachment are files added into a email message

type BatchSender

type BatchSender interface {
	Sender
	SendBatch(messages ...Message) (errorsByMessages []error, generalError error)
}

BatchSender interface for sending batch or single mail

type Body

type Body struct {
	Content     string
	ContentType string
}

Body represents one of the bodies in the Message could be main or alternative

type Message

type Message struct {
	Context     context.Context
	From        string
	To          []string
	CC          []string
	Bcc         []string
	Subject     string
	Headers     map[string]string
	Data        render.Data
	Bodies      []Body
	Attachments []Attachment
	// contains filtered or unexported fields
}

Message represents an Email message

func New

func New(c buffalo.Context) Message

New builds a new message with the current buffalo.Context

func NewFromData

func NewFromData(data render.Data) Message

NewFromData builds a new message with raw template data given

func NewMessage

func NewMessage() Message

NewMessage builds a new message.

func (*Message) AddAttachment

func (m *Message) AddAttachment(name, contentType string, r io.Reader) error

AddAttachment adds the attachment to the list of attachments the Message has.

func (*Message) AddBodies

func (m *Message) AddBodies(data render.Data, renderers ...render.Renderer) error

AddBodies Allows to add multiple bodies to the message, it returns errors that could happen in the rendering.

func (*Message) AddBody

func (m *Message) AddBody(r render.Renderer, data render.Data) error

AddBody the message by receiving a renderer and rendering data, first message will be used as the main message Body rest of them will be passed as alternative bodies on the email message

func (*Message) AddEmbedded

func (m *Message) AddEmbedded(name string, r io.Reader) error

AddEmbedded adds the attachment to the list of attachments the Message has and uses inline instead of attachement property.

func (*Message) SetHeader

func (m *Message) SetHeader(field, value string)

SetHeader sets the heder field and value for the message

type SMTPSender

type SMTPSender struct {
	Dialer *gomail.Dialer
}

SMTPSender allows to send Emails by connecting to a SMTP server.

func NewSMTPSender

func NewSMTPSender(host string, port string, user string, password string) (SMTPSender, error)

NewSMTPSender builds a SMTP mail based in passed config.

func (SMTPSender) Send

func (sm SMTPSender) Send(message Message) error

Send a message using SMTP configuration or returns an error if something goes wrong.

func (SMTPSender) SendBatch

func (sm SMTPSender) SendBatch(messages ...Message) (errorsByMessages []error, generalError error)

SendBatch of message with one connection, returns general error or errors specific for each message

type Sender

type Sender interface {
	Send(Message) error
}

Sender interface for any upcoming mailers.