ethereal

README

ethereal-go

Go client for creating temporary test email accounts on Ethereal Email using Nodemailer's provisioning API. Useful for automated tests and CI without needing real mail accounts.

Features

• Creates test SMTP, IMAP, and POP3 credentials in a single HTTP request
• Standard library integration with helpers for smtp.PlainAuth and "host:port" formatting
• Host and address checkers to detect Ethereal email domains
• Web preview URL generator for message IDs
• Standard library only, no third-party dependencies

Installation

go get github.com/fumbledlol/ethereal-go

Usage

Sending a test email

package main

import (
	"context"
	"fmt"
	"net/smtp"

	"github.com/fumbledlol/ethereal-go"
)

func main() {
	ctx := context.Background()

	// Provision new credentials
	acc, err := ethereal.CreateAccount(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Printf("User: %s\n", acc.User)
	fmt.Printf("Web inbox: %s\n", acc.Web)

	// Send an email with net/smtp
	msg := []byte("To: recipient@example.com\r\nSubject: Test Email\r\n\r\nHello from Ethereal.")
	err = smtp.SendMail(
		acc.SMTPAddr(),
		acc.Auth(),
		acc.User,
		[]string{"recipient@example.com"},
		msg,
	)
	if err != nil {
		panic(err)
	}

	fmt.Println("Message sent. Check web inbox link above.")
}

Host and address helpers

ethereal.IsEtherealHost("smtp.ethereal.email")     // true
ethereal.IsEtherealAddress("steve@ethereal.email") // true

Benchmarks

BenchmarkIsEtherealAddress-12   75256341    17.71 ns/op    0 B/op    0 allocs/op
BenchmarkIsEtherealHost-12      55537813    20.12 ns/op    0 B/op    0 allocs/op

License

MIT

Documentation

Index

• Constants
• func IsEtherealAddress(email string) bool
• func IsEtherealHost(host string) bool
• func MessageURL(messageID string) string
• type Account
  • func CreateAccount(ctx context.Context, opts ...Option) (*Account, error)
  • func (a *Account) Auth() smtp.Auth
  • func (a *Account) SMTPAddr() string
• type EndpointConfig
  • func (e EndpointConfig) Addr() string
• type Option
  • func WithEndpoint(endpoint string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithRequestor(requestor string) Option
• type Options

Constants

const DefaultAPIEndpoint = "https://api.nodemailer.com/user"

DefaultAPIEndpoint is Nodemailer's Ethereal account provisioning API.

const DefaultWebBase = "https://ethereal.email/message/"

DefaultWebBase is the web interface URL for viewing caught messages.

Functions

func IsEtherealAddress

func IsEtherealAddress(email string) bool

IsEtherealAddress reports whether the given email address belongs to the ethereal.email domain.

func IsEtherealHost

func IsEtherealHost(host string) bool

IsEtherealHost reports whether the given host name matches an Ethereal email host.

func MessageURL

func MessageURL(messageID string) string

MessageURL returns the web URL to preview a captured message by its Message-ID.

Types

type Account

type Account struct {
	Status    string         `json:"status,omitempty"`
	User      string         `json:"user"`
	Pass      string         `json:"pass"`
	SMTP      EndpointConfig `json:"smtp"`
	IMAP      EndpointConfig `json:"imap"`
	POP3      EndpointConfig `json:"pop3"`
	Web       string         `json:"web"`
	MXEnabled bool           `json:"mxEnabled,omitempty"`
}

Account holds generated Ethereal test credentials.

func CreateAccount

func CreateAccount(ctx context.Context, opts ...Option) (*Account, error)

CreateAccount calls the Ethereal API to provision a new disposable test account.

func (*Account) Auth

func (a *Account) Auth() smtp.Auth

Auth returns a standard net/smtp.Auth for sending messages via SMTP PlainAuth.

func (*Account) SMTPAddr

func (a *Account) SMTPAddr() string

SMTPAddr returns the "host:port" address for SMTP connections.

type EndpointConfig

type EndpointConfig struct {
	Host   string `json:"host"`
	Port   int    `json:"port"`
	Secure bool   `json:"secure"`
}

EndpointConfig holds connection coordinates for an email protocol.

func (EndpointConfig) Addr

func (e EndpointConfig) Addr() string

Addr returns the "host:port" address string.

type Option

type Option func(*Options)

Option modifies Options.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint overrides the provisioning API endpoint.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient overrides the HTTP client used for requests.

func WithRequestor

func WithRequestor(requestor string) Option

WithRequestor customizes the client identification sent to Nodemailer.

type Options

type Options struct {
	Endpoint   string
	Requestor  string
	HTTPClient *http.Client
}

Options configures account generation.