If you like my work, please consider supporting its development.

The email plugin allows form creators to generate and send emails based on the contents of a form submission.

There are two parts to using the email plugin: senders and form handlers.

Senders

The email plugin allows for sending emails via SMTP and using the sendmail program. Most users will want to use the SMTP sender.

Multiple email senders can be configured at a time, each with a unique name. The only reserved name is sendmail, which represents using the system sendmail program instead of an SMTP server.

All configured senders must be in the email namespace - that is, for a sender called sender1, its configuration options must appear under [email.sender1]. See the example below for a full example.

Sendmail

The email plugin assumes that the sendmail binary is available at /usr/sbin/sendmail and will return an error if it cannot find it there. No configuration is necessary to use sendmail aside from having it set up on the host system, though handlers must define a “from” email address when using sendmail.

SMTP

The email plugin can also connect to SMTP servers to send email - this is the recommended method, as it is directly supported by the email library used by the plugin.

To set up an SMTP sender, it must be given a unique name and have the following fields defined:

FieldDescriptionExample
hostThe hostname of the SMTP server."smtp.example.com"
portThe port for connecting to the SMTP server587
userThe username for authenticating with the SMTP servermy-username
passThe password for authentication with the SMTP serversupersecure
from

The default email address to use in the “From” header in the email. Will be used if not overridden in a form handler.

no-reply@example.com

Handlers

Handlers do the actual creation and sending of emails based on the form contents and use Go’s templating system to dynamically generate field contents.

Email handlers must have the following fields defined in the configuration:

FieldDescriptionExample
sender

The name of a configured SMTP sender, or "sendmail" to use the sendmail binary.

"my_smtp_sender" "sendmail"
to

The email address to send the message to. Can be a normal string or a Go template.

"admin@example.com" or see below for a template example.
subject

The subject line of the email. Can be a normal string or a Go template.

"Contact Form Submission" or see below for a template example.
bodyThe body of the email. Can be a normal string or a Go template.See below for an example using multi-line strings.
from

Required when using sendmail, optional otherwise. The email address that the email appears to be sent from.

"no-reply@example.com"

The following optional fields are also available:

FieldDescriptionExample
reply_to

The email address to reply to, instead of the one that sent it. Useful especially for contact forms, so the site admin can reply directly to the submission by email.

See below for an example using the email address from the form submission.

ccAn email address to CC the email to.other-admin@example.com
bccAn email address to BCC the email to.other-admin@example.com
files

A list of names of input fields with type file. Files will be attached to the email before it is sent.

["log_file", "other_file"]

Template Functions

Along with the standard template functions, the email plugin provides access to an email regular expression to help validate email addresses. It is available in templates as .Regexp.Email and has all related methods, though you’ll almost certainly only use MatchString.

When using .Regex.Email in templates, beware the change in dot context when using with. In the example below, .Regexp.Email is aliased to $re because, inside the with block, . is the result of FormValue "email" and no longer the global context.

Example

An important feature of TOML is that you can make multiline strings using sets of three double quotation marks (""").

The below example is an adapted version of an actual contact form using Nebula and the email plugin.

log_file = "/var/log/nebula-forms/access.log"

[email.example_smtp]
    host = "smtp.example.com"
    port = 587
    user = "username"
    pass = "supersecure"
    from = "no-reply@example.com"

[handler.email.contact_admin]
    allowed_origins = ["https://example.com"]
    honeypot = "honeypot"
    path = "/contact"
    sender = "example_smtp"
    from = "no-reply@example.com"
    to = "admin@example.com"
    reply_to = """
    {{- $er := .Regexp.Email -}}
    {{-  with (FormValue "email") -}}
        {{- if eq . "" -}}
            {{- Errorf "An email address is required." -}}
        {{- else if $er.MatchString . -}}
            {{- . -}}
        {{- else -}}
            {{- Errorf "%s doesn't look like an email address. Please enter something else." . -}}
        {{- end -}}
    {{- else -}}
        {{- Errorf "An email address is required." -}}
    {{- end -}}
"""
    subject = """
    {{- if ne (FormValue "contact_reason") "" -}}
        {{- FormValue "contact_reason" -}}
    {{- else if ne (FormValue "name") "" -}}
        Contact form submission from {{- FormValue "name" -}}
    {{- else -}}
        Contact Form Submission
    {{- end -}}
"""
    body = """
{{ FormValue "contact_reason" }}

{{ FormValue "contact_description" }}

Form submitted by {{ FormValue "name" }}
"""