Documentation - JSON API - Sending emails

If you enable the Emails option when generating your codebase, the application will be configured to support sending emails via SMTP.

Creating email templates

Email content is defined in files within the assets/emails folder. Each file should contain named templates for the email subject, plaintext body, and (optionally) an HTML body, like this:

{{define "subject"}}Example subject{{end}}

{{define "plainBody"}} 
Hi {{.Name}},

This is an example body
{{end}}
    
{{define "htmlBody"}}
<!doctype html>
<html>
    <head>
        <meta name="viewport" content="width=device-width" />
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    </head>
    <body>
        <p>Hi {{.Name}},</p>
        <p>This is an example body</p>
    </body>
</html>
{{end}}

A further example can be found in the assets/emails/example.tmpl file.

Note that email templates automatically have access to all template functions defined in the internal/funcs package.

Sending emails

Emails can be sent from your handlers, helpers, or middleware using app.mailer.Send().

For example, to send an email to alice@example.com using the contents of assets/emails/example.tmpl:

func (app *application) exampleHandler(w http.ResponseWriter, r *http.Request) {
    ...

    data := app.newEmailData()
    data["Name"] = "Alice"

    err := app.mailer.Send("alice@example.com", data, "example.tmpl")
    if err != nil {
        app.serverError(w, r, err)
        return
    }

   ...
}

The second parameter to Send() should be a map or struct containing any dynamic data you want to render in the email template.

An app.newEmailData() helper is provided in cmd/api/helpers.go, which returns a map[string]any containing common data for emails. By default, this includes the application’s BaseURL configuration setting. You can extend this helper to include any additional shared data you need.

SMTP settings

To send emails, you must configure valid SMTP settings, including the host, port, username, password, and the sender name and email address.

The available settings are:

Flag	Environment Variable	Description	Example Value
`--smtp-host`	`SMTP_HOST`	SMTP host	`example.smtp.host`
`--smtp-port`	`SMTP_PORT`	SMTP port	`25`
`--smtp-username`	`SMTP_USERNAME`	SMTP username	`example_username`
`--smtp-password`	`SMTP_PASSWORD`	SMTP password	`pa55word`
`--smtp-from`	`SMTP_FROM`	SMTP sender	`Example Name <no-reply@example.org>`

For example, if you're using command-line flags for configuration:

$ go run ./cmd/api --smtp-host="example.smtp.host" --smtp-port=25 --smtp-username="example_username" --smtp-password="pa55word" --smtp-from="Example Name <no-reply@example.org>"

For convenience during development, instead of passing command line flags each time, you may wish to change the default configuration setting values in cmd/api/main.go.

Or if you're using environment variables:

$ export SMTP_HOST="example.smtp.host"
$ export SMTP_PORT="25"
$ export SMTP_USERNAME="example_username"
$ export SMTP_PASSWORD="pa55word"
$ export SMTP_FROM="Example Name <no-reply@example.org>"

During development, you may also want to use Mailpit, MailHog, Mailtrap, or a similar tool to capture and inspect sent emails.

Note: All the email template files in the assets/email directory are embedded into your application binary and can be accessed via the EmbeddedFiles variable in assets/efs.go.