# modules/mail/smtp

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

Package smtp sends email through any SMTP server: Amazon SES, Postmark, Mailgun, Google Workspace, your own server, or Mailpit in development (ADR-0025, ADR-0037).

	sender, err := smtp.New("smtp.example.com:587",
		smtp.WithAuth(cfg.SMTPUsername, cfg.SMTPPassword),
	)

Each Send opens a connection, delivers one message and closes it. Permanent refusals (5xx replies) wrap [mail.ErrRejected](/reference/mail/#ErrRejected); everything else is temporary and safe to retry.

Stability: pre-1.0 (ADR-0015).

## Constants

### const DefaultTimeout

```go
const DefaultTimeout = 30 * time.Second
```

DefaultTimeout bounds one delivery: connecting, authenticating and sending.

## Types

### type Option

```go
type Option interface {
	// contains filtered or unexported methods
}
```

An Option configures [New](#New).

#### func WithAuth

```go
func WithAuth(username string, password config.Secret) Option
```

WithAuth authenticates with username and password (SMTP AUTH PLAIN), only over an encrypted connection or to a local server.

#### func WithLocalName

```go
func WithLocalName(name string) Option
```

WithLocalName sets the host name sent in EHLO. Default: "localhost".

#### func WithTLS

```go
func WithTLS(mode TLSMode) Option
```

WithTLS sets how the connection is encrypted. Default: [TLSStartTLS](#TLSStartTLS).

#### func WithTLSConfig

```go
func WithTLSConfig(cfg *tls.Config) Option
```

WithTLSConfig sets the TLS configuration, for example to trust a private certificate authority. Default: system roots, TLS 1.2 or later.

#### func WithTimeout

```go
func WithTimeout(d time.Duration) Option
```

WithTimeout bounds each delivery. Default: [DefaultTimeout](#DefaultTimeout).

### type Sender

```go
type Sender struct {
	// contains filtered or unexported fields
}
```

Sender delivers email over SMTP. It is safe for concurrent use.

#### func New

```go
func New(addr string, opts ...Option) (*Sender, error)
```

New returns a sender for the server at addr ("host:port").

#### func (*Sender) Send

```go
func (s *Sender) Send(ctx context.Context, m mail.Message) error
```

Send delivers m. Tags are not sent: SMTP has no standard for them.

### type TLSMode

```go
type TLSMode string
```

TLSMode is how the connection is encrypted.

#### const TLSStartTLS, …

```go
const (
	// TLSStartTLS connects in plain text, then requires STARTTLS before
	// authenticating or sending. Usually port 587.
	TLSStartTLS TLSMode = "starttls"
	// TLSImplicit uses TLS from the first byte. Usually port 465.
	TLSImplicit TLSMode = "tls"
	// TLSNone never encrypts. Use it only for local servers such as Mailpit.
	TLSNone TLSMode = "none"
)
```

TLS modes.

#### func ParseTLSMode

```go
func ParseTLSMode(s string) (TLSMode, error)
```

ParseTLSMode parses "starttls", "tls" or "none".