# mail

```go
import "apistock.dev/mail"
```

Package mail defines email messages and the [Sender](#Sender) contract implemented by provider modules such as mail/resend and mail/smtp (ADR-0025).

Stability: pre-1.0 (ADR-0015).

## Variables

### var ErrRejected

```go
var ErrRejected = errors.New("mail: rejected")
```

ErrRejected marks a send that will never succeed as it is, such as an invalid message, an unverified sender domain or a refused recipient. Providers wrap it; the jobs mail worker stops retrying such sends. Temporary failures (network errors, rate limits, provider outages) must not wrap it.

## Types

### type Address

```go
type Address struct {
	Name  string
	Email string
}
```

An Address is an email address with an optional display name.

#### func (Address) String

```go
func (a Address) String() string
```

String formats the address for an email header, quoting the name if needed.

### type Defaults

```go
type Defaults struct {
	FromName  config.Value[string]
	FromEmail config.Value[string]
	// ReplyTo is one email address; an empty value means no reply-to.
	ReplyTo config.Value[string]
}
```

Defaults are live sender values applied to messages that leave them empty. Each is read on every send, so runtime settings apply immediately. A nil field is ignored.

### type Message

```go
type Message struct {
	From    Address
	To      []Address
	ReplyTo []Address
	Subject string
	// Text and HTML are alternative bodies; at least one is required.
	Text string
	HTML string
	// IdempotencyKey lets providers drop duplicate sends, for example when a
	// background job is retried. Jobs use their job ID.
	IdempotencyKey string
	// Tags are provider metadata such as a message category.
	Tags map[string]string
}
```

A Message is an email to send. Add fields by setting them; the zero value of every optional field means "not set".

#### func (Message) Validate

```go
func (m Message) Validate() error
```

Validate reports whether m has a sender, at least one valid recipient, a subject without line breaks and a body.

### type Sender

```go
type Sender interface {
	Send(ctx context.Context, m Message) error
}
```

A Sender delivers email. Implementations must be safe for concurrent use, respect ctx cancellation and return an error when delivery fails.

#### func WithDefaults

```go
func WithDefaults(next Sender, d Defaults) Sender
```

WithDefaults returns a [Sender](#Sender) that fills an empty From and ReplyTo from d, then sends through next. Messages that set them keep their own.

### type SenderFunc

```go
type SenderFunc func(ctx context.Context, m Message) error
```

SenderFunc adapts a function to the [Sender](#Sender) interface.

#### func (SenderFunc) Send

```go
func (f SenderFunc) Send(ctx context.Context, m Message) error
```

Send calls f(ctx, m).