Skip to main content

capy_mail/
error.rs

1/// Safe error categories. Raw SMTP responses/credentials/content are never retained.
2#[derive(Clone, Copy, Debug, PartialEq, Eq)]
3pub enum MailError {
4    /// Invalid or unsafe configuration.
5    Configuration,
6    /// Invalid mailbox syntax.
7    Address,
8    /// Invalid header or control characters.
9    Header,
10    /// Invalid message structure.
11    Message,
12    /// Invalid attachment metadata or size.
13    Attachment,
14    /// Message exceeds configured bounds.
15    Size,
16    /// Template rendering failed.
17    Template,
18    /// Connection or protocol failure, conservatively retryable.
19    Connection,
20    /// Authentication rejected; operator action required.
21    Authentication,
22    /// TLS negotiation or certificate validation failed.
23    Tls,
24    /// SMTP temporary failure.
25    Temporary,
26    /// SMTP permanent failure.
27    Permanent,
28    /// Total send deadline expired; delivery may already have happened.
29    Timeout,
30    /// Test capture reached its explicit limit.
31    CaptureFull,
32    /// Queue persistence failed; commit status can be ambiguous.
33    Queue,
34}
35impl MailError {
36    /// Stable category for safe observability.
37    pub fn category(self) -> &'static str {
38        match self {
39            Self::Configuration => "configuration",
40            Self::Address => "address",
41            Self::Header => "header",
42            Self::Message => "message",
43            Self::Attachment => "attachment",
44            Self::Size => "size",
45            Self::Template => "template",
46            Self::Connection => "connection",
47            Self::Authentication => "authentication",
48            Self::Tls => "tls",
49            Self::Temporary => "temporary",
50            Self::Permanent => "permanent",
51            Self::Timeout => "timeout",
52            Self::CaptureFull => "capture_full",
53            Self::Queue => "queue",
54        }
55    }
56    /// Only temporary/connection/deadline errors are automatically retryable by Jobs.
57    pub fn retryable(self) -> bool {
58        matches!(self, Self::Temporary | Self::Connection | Self::Timeout)
59    }
60}
61impl std::fmt::Display for MailError {
62    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
63        write!(f, "Mail operation failed ({})", self.category())
64    }
65}
66impl std::error::Error for MailError {}
67impl From<askama::Error> for MailError {
68    fn from(_: askama::Error) -> Self {
69        Self::Template
70    }
71}
72impl From<MailError> for capy_core::AppError {
73    fn from(error: MailError) -> Self {
74        Self::Internal(error.into())
75    }
76}