Mailer Bridge

Transactional email delivery for verification, password resets, magic links, and invitations.

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.

Interface

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 adapter

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("noreply@myapp.com"),
        maileradapter.WithFromName("My App"),
    )),
)

Setup with a SendGrid adapter

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("noreply@myapp.com"),
    )),
)

Setup with an SMTP adapter

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:     "noreply@myapp.com",
        TLS:      true,
    })),
)

Custom implementation

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:   "noreply@myapp.com",
    }),
)

Emails sent by Authsome

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 stub

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) to=user@example.com subject=Verify your email address

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.