maily 0.2.1

A library for easy, quick, and fault tolerant sending of emails.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

// Copyright (C) 2024 Daniel Mueller <deso@posteo.net>
// SPDX-License-Identifier: GPL-3.0-or-later

use std::borrow::Cow;

#[cfg(feature = "config")]
use serde::Deserialize;


#[derive(Clone, Copy, Debug)]
#[cfg_attr(feature = "config", derive(Deserialize))]
#[non_exhaustive]
pub enum SmtpMode {
  /// Use unencrypted SMTP (typically on port 25).
  #[cfg_attr(feature = "config", serde(rename = "unencrypted"))]
  Unencrypted,
  /// Use StartTLS mode (often on port 587).
  #[cfg_attr(feature = "config", serde(rename = "starttls"))]
  StartTls,
  /// Use full TLS mode (often on port 465).
  #[cfg_attr(feature = "config", serde(rename = "tls"))]
  Tls,
}


/// A type representing a single email account.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "config", derive(Deserialize))]
pub struct Account<'input> {
  /// The hostname of the SMTP server.
  pub smtp_host: Cow<'input, str>,
  /// The SMTP "mode" to use.
  pub smtp_mode: SmtpMode,
  /// The "From" identifier to use.
  pub from: Cow<'input, str>,
  /// The user to log in as.
  pub user: Cow<'input, str>,
  /// The password to use for logging in.
  pub password: Cow<'input, str>,
}


#[cfg(feature = "config")]
#[cfg_attr(docsrs, doc(cfg(feature = "config")))]
mod implementation {
  use super::*;

  use std::marker::PhantomData;
  use std::path::Path;
  use std::path::PathBuf;

  use anyhow::Context as _;
  use anyhow::Result;

  use serde_json::from_slice as from_json;

  use tokio::fs::read;

  use crate::EmailOpts;


  /// A type representing a deserializable configuration for the
  /// email sending functionality.
  #[derive(Debug, Deserialize)]
  pub struct Config {
    /// The known accounts.
    pub accounts: Vec<Account<'static>>,
    /// The list of (default) recipients to send each email to.
    pub recipients: Vec<String>,
    /// PGP encrypt any email using the provided keybox file.
    ///
    /// The referenced keybox needs to contain public keys for all
    /// provided recipients.
    #[cfg(feature = "pgp")]
    #[cfg_attr(docsrs, doc(cfg(feature = "pgp")))]
    #[serde(alias = "pgp-keybox")]
    pub pgp_keybox: Option<PathBuf>,
  }

  impl Config {
    /// Destruct this object into constituent part directly usable as
    /// inputs to email sending APIs such as
    /// [`send_email`][crate::send_email].
    ///
    /// # Returns
    /// The function returns a tuple comprised of a list of accounts, a
    /// list of recipients, and an [`EmailOpts`] object.
    pub fn into_inputs(self) -> (Vec<Account<'static>>, Vec<String>, EmailOpts<'static>) {
      let Self {
        accounts,
        recipients,
        #[cfg(feature = "pgp")]
        pgp_keybox,
      } = self;

      let opts = EmailOpts {
        #[cfg(feature = "pgp")]
        pgp_keybox: pgp_keybox.map(Cow::Owned),
        _phantom: PhantomData,
      };

      (accounts, recipients, opts)
    }
  }


  /// Retrieve the path to the system configuration.
  #[inline]
  pub fn system_config_path() -> Result<Cow<'static, Path>> {
    let path = Cow::Borrowed(Path::new("/etc/maily/config.json"));
    Ok(path)
  }


  /// Load the system configuration.
  pub async fn system_config() -> Result<Config> {
    let path = system_config_path().context("failed to retrieve path to system configuration")?;
    let data = read(&path)
      .await
      .with_context(|| format!("failed to read configuration file `{}`", path.display()))?;
    let config = from_json::<Config>(&data)
      .with_context(|| format!("failed to parse `{}` contents as JSON", path.display()))?;
    Ok(config)
  }
}

#[cfg(feature = "config")]
pub use implementation::*;