Smtppool

https://pkg.go.dev/github.com/knadh/smtppool
Admin
Smtppool is a Go library that creates a pool of reusable SMTP connections for high throughput...
Tokens:3,866
Snippets:43
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### LoginAuth.Start

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Starts the SMTP LOGIN authentication process with the server.

```APIDOC
## LoginAuth.Start

### Description
Start starts the SMTP LOGIN auth type. https://gist.github.com/andelf/5118732

### Method
```go
func (a *LoginAuth) Start(server *smtp.ServerInfo) (string, []byte, error)
```
```

--------------------------------

### SMTP LOGIN Auth Start

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Implements the Start method for SMTP LOGIN authentication, initiating the authentication process with server information.

```go
func (a *LoginAuth) Start(server *smtp.ServerInfo) (string, []byte, error)
```

--------------------------------

### Create and Send Email with smtppool

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Demonstrates how to create an SMTP connection pool and send an email. Ensure a local SMTP server is running (e.g., MailHog) on localhost:1025. Attachments can be added using AttachFile.

```go
package main

import (
	"log"
	"time"

	"github.com/knadh/smtppool/v2"
)

func main() {
	// Try https://github.com/mailhog/MailHog for running a local dummy SMTP server.
	// Create a new pool.
	pool, err := smtppool.New(smtppool.Opt{
		Host:            "localhost",
		Port:            1025,
		MaxConns:        10,
		IdleTimeout:     time.Second * 10,
		PoolWaitTimeout: time.Second * 3,
		SSL:             smtppool.SSLNone
	})
	if err != nil {
		log.Fatalf("error creating pool: %v", err)
	}

	e:= smtppool.Email{
		From:    "John Doe <john@example.com>",
		To:      []string{"doe@example.com"},

		// Optional.
		Bcc:     []string{"doebcc@example.com"},
		Cc:      []string{"doecc@example.com"},

		Subject: "Hello, World",
		Text:    []byte("This is a test e-mail"),
		HTML:    []byte("<strong>This is a test e-mail</strong>"),
	}

	// Add attachments.
	if _, err := e.AttachFile("test.txt"); err != nil {
		log.Fatalf("error attaching file: %v", err)
	}

	if err := pool.Send(e); err != nil {
		log.Fatalf("error sending e-mail: %v", err)
	}
}

```

--------------------------------

### New Pool Creation and Email Sending

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Demonstrates how to create a new smtppool and send an email using it. Includes configuration options for the pool and email content.

```APIDOC
## New Pool Creation and Email Sending

### Description
This example shows how to initialize a new SMTP connection pool and send a basic email. It covers setting up pool options like host, port, connection limits, and timeouts, as well as constructing an email with recipients, subject, text, and HTML content.

### Usage
```go
package main

import (
	"log"
	"time"

	"github.com/knadh/smtppool/v2"
)

func main() {
	// Try https://github.com/mailhog/MailHog for running a local dummy SMTP server.
	// Create a new pool.
	pool, err := smtppool.New(smtppool.Opt{
		Host:            "localhost",
		Port:            1025,
		MaxConns:        10,
		IdleTimeout:     time.Second * 10,
		PoolWaitTimeout: time.Second * 3,
		SSL:             smtppool.SSLNone
	})
	if err != nil {
		log.Fatalf("error creating pool: %v", err)
	}

	e:= smtppool.Email{
		From:    "John Doe <john@example.com>",
		To:      []string{"doe@example.com"},

		// Optional.
		Bcc:     []string{"doebcc@example.com"},
		Cc:      []string{"doecc@example.com"},

		Subject: "Hello, World",
		Text:    []byte("This is a test e-mail"),
		HTML:    []byte("<strong>This is a test e-mail</strong>"),
	}

	// Add attachments.
	if _, err := e.AttachFile("test.txt"); err != nil {
		log.Fatalf("error attaching file: %v", err)
	}

	if err := pool.Send(e); err != nil {
		log.Fatalf("error sending e-mail: %v", err)
	}
}
```

### Pool Options (`smtppool.Opt`)
- **Host** (string) - The SMTP server hostname.
- **Port** (int) - The SMTP server port.
- **MaxConns** (int) - The maximum number of concurrent SMTP connections to maintain.
- **IdleTimeout** (time.Duration) - The duration after which an idle connection will be closed.
- **PoolWaitTimeout** (time.Duration) - The maximum time to wait for a connection from the pool.
- **SSL** (smtppool.SSLType) - The SSL/TLS configuration for the connection.

### Email Structure (`smtppool.Email`)
- **From** (string) - The sender's email address.
- **To** ([]string) - A list of recipient email addresses.
- **Bcc** ([]string) - Optional: A list of blind carbon copy recipient email addresses.
- **Cc** ([]string) - Optional: A list of carbon copy recipient email addresses.
- **Subject** (string) - The email subject.
- **Text** ([]byte) - The plain text content of the email.
- **HTML** ([]byte) - The HTML content of the email.

### Methods
- **`smtppool.New(o Opt) (*Pool, error)`**: Creates and returns a new `Pool` instance with the given options.
- **`(*Pool) Send(e Email) error`**: Sends the provided `Email` using a connection from the pool.
```

--------------------------------

### SMTP LOGIN Auth Next Step

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Implements the Next method for SMTP LOGIN authentication, passing credentials to the server.

```go
func (a *LoginAuth) Next(fromServer []byte, more bool) ([]byte, error)
```

--------------------------------

### Initialize SMTP Pool

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Initializes and returns a new SMTP connection pool based on the provided options. Ensure the Opt struct is correctly configured before calling.

```go
func New(o Opt) (*Pool, error)
```

--------------------------------

### Define SSL Connection Types

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Defines the possible types of SSL/TLS connections for SMTP: none, direct SSL/TLS, or STARTTLS.

```go
type SSLType uint8
```

```go
const (
	// SSLNone specifies a plain unencrypted connection.
	SSLNone SSLType = iota

	// SSLTLS specifies an SSL (TLS) connection without the STARTTLS extension.
	SSLTLS

	// SSLSTARTTLS specifies a non-TLS connection that then upgrades to STARTTLS.
	SSLSTARTTLS
)
```

--------------------------------

### New Pool

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Initializes and returns a new SMTP connection pool with the specified options.

```APIDOC
## New Pool

### Description
New initializes and returns a new SMTP Pool.

### Method
```go
func New(o Opt) (*Pool, error)
```
```

--------------------------------

### Email Header Constants

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Provides constants for common SMTP and MIME headers.

```go
const (
	HdrContentType = "Content-Type"
	HdrSubject     = "Subject"
	HdrTo          = "To"
	HdrCC          = "Cc"
	HdrBCC         = "Bcc"
	HdrFrom        = "From"
	HdrReplyTo     = "Reply-To"
	HdrDate        = "Date"
	HdrMessageID   = "Message-Id"
	HdrMimeVersion = "MIME-Version"

	HdrContentTransferEncoding = "Content-Transfer-Encoding"
	HdrContentDisposition      = "Content-Disposition"
	HdrContentID               = "Content-ID"
)

```

--------------------------------

### Attach File to Email

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Attaches content from a local file to the email. The function opens the specified file and appends it as an Attachment. Returns the created Attachment.

```go
func (e *Email) AttachFile(filename string) (a Attachment, err error)
```

--------------------------------

### LoginAuth.Next

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Provides credentials for the SMTP LOGIN authentication.

```APIDOC
## LoginAuth.Next

### Description
Next passes the credentials for SMTP LOGIN auth type.

### Method
```go
func (a *LoginAuth) Next(fromServer []byte, more bool) ([]byte, error)
```
```

--------------------------------

### Define LoginAuth Structure

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Defines the structure for SMTP LOGIN authentication, holding username and password credentials.

```go
type LoginAuth struct {
	Username string
	Password string
}
```

--------------------------------

### Create Email from Reader

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Parses RFC 5322 formatted data from an io.Reader to create an Email struct. Ensure the input stream conforms to the RFC specification.

```go
func NewEmailFromReader(r io.Reader) (Email, error)
```

--------------------------------

### Define SMTP Pool Options

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Defines the configuration options for an SMTP connection pool, including host, port, connection limits, timeouts, and authentication settings.

```go
type Opt struct {
	// Host is the SMTP server's hostname.
	Host string `json:"host"`

	// Port is the SMTP server port.
	Port int `json:"port"`

	// HelloHostname is the optional hostname to pass with the HELO command.
	// Default is "localhost".
	HelloHostname string `json:"hello_hostname"`

	// MaxConns is the maximum allowed concurrent SMTP connections.
	MaxConns int `json:"max_conns"`

	// MaxMessageRetries is the number of times a message should be retried
	// if sending fails. Default is 2. Min is 1.
	MaxMessageRetries int `json:"max_msg_retries"`

	// MsgRetryDelay (optional) is the duration to wait before retrying a failed message.
	MsgRetryDelay time.Duration `json:"msg_retry_delay"`

	// IdleTimeout is the maximum time to wait for new activity on a connection
	// before closing it and removing it from the pool.
	IdleTimeout time.Duration `json:"idle_timeout"`

	// PoolWaitTimeout is the maximum time to wait to obtain a connection from
	// a pool before timing out. This may happen when all open connections are
	// busy sending e-mails and they're not returning to the pool fast enough.
	// This is also the timeout used when creating new SMTP connections.
	PoolWaitTimeout time.Duration `json:"wait_timeout"`

	// Given TLSConfig:
	// SSLNone (default); open a plain unencrypted connection.
	// SSLTLS; use an SSL (TLS) connection without the STARTTLS extension.
	// SSLSTARTTLS; open a non-TLS connection and then requests the STARTTLS extension.
	SSL SSLType `json:"ssl"`

	// Auth is the smtp.Auth authentication scheme.
	Auth smtp.Auth

	// TLSConfig is the optional TLS configuration.
	TLSConfig *tls.Config
}
```

--------------------------------

### Attach Content to Email

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Attaches content from an io.Reader as a file to the email. Requires the reader, a filename, and the Content-Type. Returns the created Attachment.

```go
func (e *Email) Attach(r io.Reader, filename string, c string) (a Attachment, err error)
```

--------------------------------

### Define Email Structure

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Defines the structure for an email message, including fields for recipients, subject, body (plain text and HTML), attachments, and headers.

```go
type Email struct {
	ReplyTo []string
	From    string
	To      []string
	Bcc     []string
	Cc      []string
	Subject string

	// Text is the optional plain text form of the message.
	Text []byte

	// HTML is the optional HTML form of the message.
	HTML []byte

	// Sender overrides From as SMTP envelope sender (optional).
	Sender      string
	Headers     textproto.MIMEHeader
	Attachments []Attachment
	ReadReceipt []string
}
```

--------------------------------

### Convert Email to Bytes

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Converts the Email object into a byte slice, including all necessary MIME headers and boundaries for sending.

```go
func (e *Email) Bytes() ([]byte, error)
```

--------------------------------

### NewEmailFromReader

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Creates a new Email struct by reading and parsing RFC 5322 formatted data from an io.Reader.

```APIDOC
## NewEmailFromReader

### Description
Reads a stream of bytes from an io.Reader, r, and returns an email struct containing the parsed data. This function expects the data in RFC 5322 format.

### Function Signature
```go
func NewEmailFromReader(r io.Reader) (Email, error)
```
```

--------------------------------

### Email.AttachFile

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Attaches a file to the email by its filename.

```APIDOC
## Email.AttachFile

### Description
AttachFile is used to attach content to the email. It attempts to open the file referenced by filename and, if successful, creates an Attachment. This Attachment is then appended to the slice of Email.Attachments. The function will then return the Attachment for reference, as well as nil for the error, if successful.

### Method
```go
func (e *Email) AttachFile(filename string) (a Attachment, err error)
```
```

--------------------------------

### Send Email via Pool

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Sends an email using an available connection from the pool. If sending fails, the message will be retried on a new connection.

```go
func (p *Pool) Send(e Email) error
```

--------------------------------

### Email Content Type Constants

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Defines constants for various email content types used in MIME multipart messages.

```go
const (
	ContentTypePlain            = "text/plain"
	ContentTypeHTML             = "text/html"
	ContentTypeOctetStream      = "application/octet-stream"
	ContentTypeMultipartAlt     = "multipart/alternative"
	ContentTypeMultipartMixed   = "multipart/mixed"
	ContentTypeMultipartRelated = "multipart/related"

	// MaxLineLength is the maximum line length per RFC 2045.
	MaxLineLength = 76
)

```

--------------------------------

### Email.Attach

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Attaches content from an io.Reader to an email as an attachment.

```APIDOC
## Email.Attach

### Description
Attach is used to attach content from an io.Reader to the email. Required parameters include an io.Reader, the desired filename for the attachment, and the Content-Type. The function will return the created Attachment for reference, as well as nil for the error, if successful.

### Method
```go
func (e *Email) Attach(r io.Reader, filename string, c string) (a Attachment, err error)
```
```

--------------------------------

### Pool.Send

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Sends an email using an available connection from the pool. If an error occurs, the message will be retried on a new connection.

```APIDOC
## Pool.Send

### Description
Send sends an e-mail using an available connection in the pool. On error, the message is retried on a new connection.

### Method
```go
func (p *Pool) Send(e Email) error
```
```

--------------------------------

### Email.Bytes

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Converts the Email object into a byte slice representation, including necessary MIME headers and boundaries.

```APIDOC
## Email.Bytes

### Description
Bytes converts the Email object to a []byte representation, including all needed MIMEHeaders, boundaries, etc.

### Method
```go
func (e *Email) Bytes() ([]byte, error)
```
```

--------------------------------

### SMTP Pool Error Constants

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Defines errors that can be returned by the smtppool package, such as when attempting to use a closed pool.

```go
var ErrPoolClosed = errors.New("pool closed")

```

--------------------------------

### Pool.Close

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Closes the SMTP connection pool, releasing all resources.

```APIDOC
## Pool.Close

### Description
Close closes the pool.

### Method
```go
func (p *Pool) Close()
```
```

--------------------------------

### Close SMTP Pool

Source: https://pkg.go.dev/github.com/knadh/smtppool/v2

Closes the SMTP connection pool, releasing all resources and active connections.

```go
func (p *Pool) Close()
```
Tokens:
Raw