Getting started

Table of contents

• Requirements
• Installation
• Sending your first mail
  • Create a new message
  • Delivering the message
  • Conclusion
  • Full example code

Requirements

go-mail requires a working Go installation. Currently we require at least Go 1.16, but since the Go team only maintains the last two releases, it is advised to use the latest Go release available on the Go Downloads page.

Installation

go-mail can be installed using the Go module installation mechanism via the go get command.

To install the latest version of go-mail, enter your project folder and simply import the module by issuing the following command:

$ go get github.com/wneessen/go-mail

Please keep in mind, that go-mail is a package and not a standalone application. There will be no go-mail application for you to execute.

Sending your first mail

go-mail consists of two main components. The Msg type, which represents the mail message and the Client type which takes care of the mail delivery via a SMTP service.

Create a new message

First let's create a new Msg using the NewMsg() method and assign a sender address as well as a recipient address.

package main

import (
	"log"

	"github.com/wneessen/go-mail"
)

func main() {
	message := mail.NewMsg()
	if err := message.From("toni.sender@example.com"); err != nil {
		log.Fatalf("failed to set From address: %s", err)
	}
	if err := message.To("tina.recipient@example.com"); err != nil {
		log.Fatalf("failed to set To address: %s", err)
	}
}

In this little code snippet, first and foremost we import go-mail into our project (see the import statement). Next we create a new message using the mail.NewMsg() method. In the following lines, we use the From() and To() methods to set the sender and recipient addresses for our Msg. Since go-mail makes sure that you are providing valid mail addresses, we return an error. This way we can make sure that the provided address is accepted by go-mail and will not cause problems later on.

Next we want to set a subject line for our message and fill the mail body with some content.

	message.Subject("This is my first mail with go-mail!")
	message.SetBodyString(mail.TypeTextPlain, "Do you like this mail? I certainly do!")

We use the Subject() method to add a subject line to our Msg and then use SetBodyString() to set a simple string as our message body. The first argument for SetBodyString() is a content type. In our example the mail.TypeTextPlain basically represents a text/plain content type - meaning a plain text mail body.

Delivering the message

Now that we have our very basic mail message ready, let's bring it on its way and deliver it via SMTP. For this we'll use the Client, which handles all the SMTP transmission stuff like i. e. TLS and authentication.

	client, err := mail.NewClient("smtp.example.com", mail.WithSMTPAuth(mail.SMTPAuthPlain),
		mail.WithUsername("my_username"), mail.WithPassword("extremely_secret_pass"))
	if err != nil {
		log.Fatalf("failed to create mail client: %s", err)
	}

In this code snippet we connect to the mail server with the hostname smtp.example.com and provide the Client with a couple of options like the type of SMTP authentication we want to use (SMTP PLAIN in this case), and the username and password for the authentication.

Eventually we instruct our client to deliver the mail.

	if err := client.DialAndSend(message); err != nil {
		log.Fatalf("failed to send mail: %s", err)
	}

The DialAndSend() method takes care of establishing a connection with the server and delivering the mail. You have the option to call the dial and send methods separately as well, but we won't need this in this quick example.

Conclusion

That was quite simple, wasn't it? You successfully prepared a mail message and delivered it to the recipient via a 3rd party mail server. go-mail of course can do much more. Check out the in-depth documentation for all the features.

Full example code

Test on play.go.dev

package main

import (
	"log"

	"github.com/wneessen/go-mail"
)

func main() {
	message := mail.NewMsg()
	if err := message.From("toni.sender@example.com"); err != nil {
		log.Fatalf("failed to set From address: %s", err)
	}
	if err := message.To("tina.recipient@example.com"); err != nil {
		log.Fatalf("failed to set To address: %s", err)
	}
	message.Subject("This is my first mail with go-mail!")
	message.SetBodyString(mail.TypeTextPlain, "Do you like this mail? I certainly do!")
	client, err := mail.NewClient("smtp.example.com", mail.WithSMTPAuth(mail.SMTPAuthPlain),
		mail.WithUsername("my_username"), mail.WithPassword("extremely_secret_pass"))
	if err != nil {
		log.Fatalf("failed to create mail client: %s", err)
	}
	if err := client.DialAndSend(message); err != nil {
		log.Fatalf("failed to send mail: %s", err)
	}
}