Email Plugin

The email plugin sends transactional emails for authentication events -- welcome emails on sign-up, verification emails for new users, password reset emails, and organization invitation emails. It integrates with the Mailer bridge to deliver emails through any configured provider.

Setup

import (
    "github.com/xraph/authsome"
    "github.com/xraph/authsome/plugins/email"
)

eng, err := authsome.NewEngine(
    authsome.WithStore(store),
    authsome.WithMailer(mailerBridge),
    authsome.WithPlugin(email.New(email.Config{
        From:    "noreply@example.com",
        AppName: "My App",
        BaseURL: "https://example.com",
    })),
)

Configuration

Implemented interfaces

Email verification flow

When a new user is created with an unverified email, the plugin sends a verification email automatically via the AfterUserCreate hook:

1. The engine creates the user record
2. The email plugin receives the OnAfterUserCreate callback
3. If EmailVerified is false, the plugin sends a verification email with a link to {BaseURL}/verify-email
4. The user clicks the link, which calls POST /v1/auth/verify-email with the verification token

// The verification email includes a link like:
// https://example.com/verify-email?token=abc123

If the user's email is already verified (for example, via SSO), no verification email is sent.

Welcome email

On sign-up, the plugin sends a welcome email via the AfterSignUp hook. The welcome email is separate from the verification email and is sent regardless of verification status.

// The plugin resolves the user's display name:
name := u.Name
if name == "" {
    name = u.Email
}

subject, html, text := WelcomeEmail(name, cfg.AppName)

Password reset email

The SendPasswordReset method is called by the engine's password reset flow. It is not a hook -- the engine calls it directly when a password reset is requested:

err := emailPlugin.SendPasswordReset(ctx, email, name, resetURL)

The reset URL includes the token so the user can complete the reset process.

Invitation email

The SendInvitation method sends organization invitation emails:

err := emailPlugin.SendInvitation(ctx, email, inviterName, orgName, acceptURL)

Email templates

The plugin includes built-in HTML and text templates for each email type:

Templates are defined in the templates.go file within the email plugin package.

Integration with Mailer bridge

The email plugin requires a Mailer bridge to be configured on the engine. If no mailer is available, the plugin silently skips all email operations -- it never returns an error from hook callbacks.

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

// EmailMessage structure:
type EmailMessage struct {
    To      []string
    From    string
    Subject string
    HTML    string
    Text    string
}

Testing

For testing, inject a mock mailer directly:

p := email.New(email.Config{
    From:    "test@example.com",
    AppName: "TestApp",
    BaseURL: "https://test.example.com",
})
p.SetMailer(mockMailer)