Mailer Bridge

The Mailer bridge provides transactional email delivery for all Authsome email notifications: email address verification, password reset links, magic link sign-in, and organisation invitations. You provide the mailer implementation; Authsome provides the message content.

If you need multi-channel delivery (email + SMS + push) or template management, use the Herald bridge instead — Herald supersedes both the Mailer and SMS bridges when configured.

Interface01

The bridge.Mailer interface is defined in github.com/xraph/authsome/bridge:

type Mailer interface {
    SendEmail(ctx context.Context, msg *EmailMessage) error
}

type EmailMessage struct {
    To      []string `json:"to"`
    From    string   `json:"from,omitempty"` // Falls back to configured default sender
    Subject string   `json:"subject"`
    HTML    string   `json:"html,omitempty"`
    Text    string   `json:"text,omitempty"` // Plain-text fallback
}

Setup with a Resend adapter02

import (
    "github.com/xraph/authsome"
    "github.com/xraph/authsome/bridge/maileradapter"
)

eng, err := authsome.New(
    authsome.WithStore(pgStore),
    authsome.WithPlugin(password.New()),
    authsome.WithMailer(maileradapter.NewResend(os.Getenv("RESEND_API_KEY"),
        maileradapter.WithFromAddress("[email protected]"),
        maileradapter.WithFromName("My App"),
    )),
)

Setup with a SendGrid adapter03

import "github.com/xraph/authsome/bridge/maileradapter"

eng, err := authsome.New(
    authsome.WithStore(pgStore),
    authsome.WithMailer(maileradapter.NewSendGrid(os.Getenv("SENDGRID_API_KEY"),
        maileradapter.WithFromAddress("[email protected]"),
    )),
)

Setup with an SMTP adapter04

import "github.com/xraph/authsome/bridge/maileradapter"

eng, err := authsome.New(
    authsome.WithStore(pgStore),
    authsome.WithMailer(maileradapter.NewSMTP(maileradapter.SMTPConfig{
        Host:     "smtp.example.com",
        Port:     587,
        Username: os.Getenv("SMTP_USERNAME"),
        Password: os.Getenv("SMTP_PASSWORD"),
        From:     "[email protected]",
        TLS:      true,
    })),
)

Custom implementation05

Implement bridge.Mailer directly for any email provider:

type PostmarkMailer struct {
    client *postmark.Client
    from   string
}

func (m *PostmarkMailer) SendEmail(ctx context.Context, msg *bridge.EmailMessage) error {
    _, err := m.client.SendEmail(postmark.Email{
        From:     m.from,
        To:       strings.Join(msg.To, ","),
        Subject:  msg.Subject,
        HTMLBody: msg.HTML,
        TextBody: msg.Text,
    })
    return err
}

eng, err := authsome.New(
    authsome.WithStore(pgStore),
    authsome.WithMailer(&PostmarkMailer{
        client: postmark.NewClient(os.Getenv("POSTMARK_TOKEN"), ""),
        from:   "[email protected]",
    }),
)

Emails sent by Authsome06

Email	Trigger	Subject
Email verification	User signs up	"Verify your email address"
Password reset	User requests reset	"Reset your password"
Magic link	User requests magic link sign-in	"Sign in to [App Name]"
Organisation invitation	Admin invites member	"You've been invited to [Org Name]"
Welcome email	User completes registration	"Welcome to [App Name]"

The subject lines and HTML/text body content are generated by Authsome's built-in templates. If you want fully customised email content and templates, use the Herald bridge which provides a full template management system.

Standalone development stub07

During development, use the built-in NoopMailer that logs all outgoing emails at debug level:

import (
    "log/slog"
    "github.com/xraph/authsome/bridge"
)

eng, err := authsome.New(
    authsome.WithStore(memory.New()),
    authsome.WithMailer(bridge.NewNoopMailer(slog.Default())),
)

Log output:

DEBUG authsome mailer (noop) [email protected] subject=Verify your email address

Note

When no Mailer bridge is configured (and no Herald bridge either), Authsome's password and magic link plugins will still function but will not send email. Users will not receive verification emails, password reset links, or magic links. Always configure a mailer in production.

← Previous

Keysmith Bridge

SMS Bridge