Debian Codegraph @

pkg/services/email/smtp/doc.go

raw
1 // Package smtp provides a service for sending email notifications via the Simple Mail Transfer Protocol (SMTP).
2 // It is part of the shoutrrr notification framework and supports sending notifications to email recipients with configurable
3 // authentication, encryption, and message formatting options.
4 //
5 // The package supports the following features:
6 // - Authentication methods: None, Plain, CRAM-MD5, and OAuth2.
7 // - Encryption methods: None, ExplicitTLS (using STARTTLS), ImplicitTLS (TLS for the entire session), and Auto (port-based selection).
8 // - Message formats: Plain text or HTML with multipart/alternative support.
9 // - Configuration via a URL scheme (e.g., `smtp://user:password@host:port/[email protected]&[email protected]`).
10 // - Integration with the shoutrrr framework for extensible notification delivery.
11 //
12 // # Usage
13 //
14 // To use the SMTP service, you must initialize a [Service] instance with a valid configuration URL and a logger.
15 // The configuration URL specifies the SMTP server details, authentication credentials, and email parameters.
16 // Below is an example of how to initialize and send an email notification:
17 //
18 // package main
19 //
20 // import (
21 // "log"
22 // "net/url"
23 // "github.com/nicholas-fedor/shoutrrr/pkg/services/email/smtp"
24 // "github.com/nicholas-fedor/shoutrrr/pkg/types"
25 // )
26 //
27 // func main() {
28 // logger := log.New(log.Writer(), "smtp: ", log.LstdFlags)
29 // service := &smtp.Service{}
30 //
31 // serviceURL, err := url.Parse("smtp://user:[email protected]:587/[email protected]&[email protected]&subject=Test%20Notification&useStartTLS=yes&useHTML=no")
32 // if err != nil {
33 // log.Fatalf("Failed to parse URL: %v", err)
34 // }
35 //
36 // err = service.Initialize(serviceURL, logger)
37 // if err != nil {
38 // log.Fatalf("Failed to initialize service: %v", err)
39 // }
40 //
41 // err = service.Send("This is a test notification.", nil)
42 // if err != nil {
43 // log.Fatalf("Failed to send notification: %v", err)
44 // }
45 // log.Println("Notification sent successfully!")
46 // }
47 //
48 // # Configuration
49 //
50 // The [Config] struct defines the parameters for the SMTP service, which can be set via a URL or programmatically.
51 // Key configuration fields include:
52 // - Host: The SMTP server hostname or IP address.
53 // - Port: The SMTP server port (e.g., 25, 465, 587, or 2525).
54 // - Username and Password: Credentials for authentication (if required).
55 // - FromAddress and FromName: The sender's email address and display name.
56 // - ToAddresses: A list of recipient email addresses.
57 // - Subject: The email subject (defaults to "Shoutrrr Notification").
58 // - Auth: The authentication method (None, Plain, CRAMMD5, OAuth2, or Unknown).
59 // - Encryption: The encryption method (None, ExplicitTLS, ImplicitTLS, or Auto).
60 // - UseStartTLS: Whether to use STARTTLS for encryption (default: true).
61 // - UseHTML: Whether to send the message as HTML (default: false).
62 // - ClientHost: The client hostname used in the SMTP handshake (default: "localhost").
63 // - RequireStartTLS: Whether to fail if StartTLS is enabled but unsupported (default: false).
64 // - Timeout: Duration for SMTP operations timeout (default: 10 seconds).
65 //
66 // The configuration URL follows the format:
67 //
68 // `smtp://<username>:<password>@<host>:<port>/?fromAddress=<email>&toAddresses=<email1>,<email2>&subject=<subject>&auth=<auth>&encryption=<encryption>&useStartTLS=<yes/no>&useHTML=<yes/no>&clientHost=<hostname>&requirestarttls=<yes/no>&timeout=<duration>`
69 //
70 // Example URL:
71 //
72 // `smtp://user:[email protected]:587/[email protected]&[email protected],[email protected]&subject=Alert&auth=Plain&encryption=Auto&useStartTLS=yes&useHTML=yes&clientHost=localhost&requirestarttls=yes&timeout=10s`
73 //
74 // # Error Handling
75 //
76 // The package defines a set of failure identifiers in `smtp_failures.go` (e.g., [FailGetSMTPClient], [FailAuthenticating], [FailSendRecipient])
77 // to categorize errors that may occur during SMTP operations. These are wrapped using the [failures.Failure] interface
78 // from the shoutrrr framework, providing detailed error messages and IDs for debugging.
79 //
80 // # Authentication
81 //
82 // The package supports multiple authentication methods, defined in [authType] and [AuthTypes]:
83 // - None: No authentication.
84 // - Plain: Username and password-based authentication.
85 // - CRAMMD5: Challenge-response authentication using CRAM-MD5.
86 // - OAuth2: Token-based authentication for services like Gmail (see [OAuth2Auth]).
87 // Note that OAuth2 support is limited to static access tokens and does not
88 // handle token refresh or complex challenge-response flows.
89 // - Unknown: Fallback when the authentication method is not specified or invalid.
90 //
91 // # Encryption
92 //
93 // Encryption is configured via the [encMethod] type and [EncMethods] helper, supporting:
94 // - None: No encryption.
95 // - ExplicitTLS: Uses STARTTLS to initiate a secure connection.
96 // - ImplicitTLS: Uses TLS for the entire session (typically on port 465).
97 // - Auto: Automatically selects ImplicitTLS for port 465, otherwise attempts ExplicitTLS if supported.
98 //
99 // The [useImplicitTLS] function determines whether ImplicitTLS should be used based on the encryption method and port.
100 //
101 // # Testing
102 //
103 // The `smtp_test.go` file includes unit and integration tests using the Ginkgo and Gomega frameworks.
104 // Tests cover configuration parsing, email sending, error handling, and integration scenarios with mocked SMTP server responses.
105 // The [testIntegration] and [testSendRecipient] functions simulate SMTP server interactions for testing purposes.
106 //
107 // # Notes
108 //
109 // - The package uses the standard Go `net/smtp` library for SMTP operations.
110 // - It supports multipart email messages (plain text and HTML) using a randomly generated boundary.
111 // - The [Service] struct implements the shoutrrr [standard.Standard] and [standard.Templater] interfaces for logging and message templating.
112 // - The package handles plus signs (`+`) in email addresses correctly, replacing spaces with plus signs as needed (see [Config.FixEmailTags]).
113 // - For OAuth2 authentication, the [OAuth2Auth] function implements the SASL XOAUTH2 protocol, suitable for services like Gmail.
114 package smtp