[PATCH proxmox 1/1] sendmail: add additional header map

[PATCH proxmox 1/1] sendmail: add additional header map

[Nicolas Frey]

with corresponding methods to add them.

this does not check for duplicates for the ones already set by other
fields/defaults (e.g. To, From, Content-Type, etc.)

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 proxmox-sendmail/src/lib.rs | 47 +++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/proxmox-sendmail/src/lib.rs b/proxmox-sendmail/src/lib.rs
index db751305..355a84c2 100644
--- a/proxmox-sendmail/src/lib.rs
+++ b/proxmox-sendmail/src/lib.rs
@@ -3,6 +3,7 @@
 //! and alternative html parts to one or multiple receivers via ``sendmail``.
 //!
 
+use std::collections::HashMap;
 use std::io::Write;
 use std::process::{Command, Stdio};
 
@@ -247,6 +248,7 @@ pub struct Mail<'a> {
     attachments: Vec<Attachment<'a>>,
     mask_participants: bool,
     noreply: Option<Recipient>,
+    additional_headers: HashMap<String, String>,
 }
 
 impl<'a> Mail<'a> {
@@ -265,6 +267,7 @@ impl<'a> Mail<'a> {
             attachments: Vec::new(),
             mask_participants: true,
             noreply: None,
+            additional_headers: HashMap::new(),
         }
     }
 
@@ -393,6 +396,20 @@ impl<'a> Mail<'a> {
         self
     }
 
+    /// Set an arbitrary header to be sent in addition to the default ones already set up by other
+    /// methods.
+    pub fn set_header<S: ToString>(&mut self, name: S, body: S) {
+        self.additional_headers
+            .insert(name.to_string(), body.to_string());
+    }
+
+    /// Builder-style method to set an arbitrary header in addition to the default ones already
+    /// set up by other methods.
+    pub fn with_header<S: ToString>(mut self, name: S, body: S) -> Self {
+        self.set_header(name, body);
+        self
+    }
+
     /// Sends the email. This will fail if no recipients have been added.
     ///
     /// Note: An `Auto-Submitted: auto-generated` header is added to avoid triggering OOO and
@@ -584,6 +601,11 @@ impl<'a> Mail<'a> {
         let rfc2822_date = proxmox_time::epoch_to_rfc2822(now)
             .with_context(|| "could not convert epoch to rfc2822 date")?;
         writeln!(header, "Date: {rfc2822_date}")?;
+
+        for (name, body) in &self.additional_headers {
+            writeln!(header, "{name}: {body}")?;
+        }
+
         header.push_str("Auto-Submitted: auto-generated;\n");
 
         Ok(header)
@@ -681,6 +703,31 @@ mod test {
         assert!(result.is_err());
     }
 
+    #[test]
+    fn additional_headers() {
+        let mail = Mail::new("Sender", "mail@example.com", "hi", "body")
+            .with_recipient_and_name("Jane Doe", "j.doe@example.com")
+            .with_header("Reply-To", "mail@example.com")
+            .with_header("CC", "cc1@example.com,cc2@example.com");
+        let body = mail.format_mail(0).expect("could not format mail");
+
+        assert_lines_equal_ignore_date(
+            &body,
+            r#"Subject: hi
+From: Sender <mail@example.com>
+To: Jane Doe <j.doe@example.com>
+Date: Thu, 01 Jan 1970 01:00:00 +0100
+Reply-To: mail@example.com
+CC: cc1@example.com,cc2@example.com
+Auto-Submitted: auto-generated;
+Content-Type: text/plain;
+	charset="UTF-8"
+Content-Transfer-Encoding: 7bit
+
+body"#,
+        )
+    }
+
     #[test]
     fn simple_ascii_text_mail() {
         let mail = Mail::new(
-- 
2.47.3

Re: [PATCH proxmox 1/1] sendmail: add additional header map

[Shannon Sterz]

On Mon Jun 15, 2026 at 11:20 AM CEST, Nicolas Frey wrote:
> with corresponding methods to add them.
>

generally i like the idea of allowing callers to specify additional
headers, but i wonder if this is a bit too lenient. usually, we try to
handle all encoding and formatting for the caller here, so we can deal
with being in compliance with all rfcs and mail related conventions here
instead of all call-sites.

also this would allow setting headers that are set by proxmox-sendmail
anyway twice. that's probably not ideal either.

so imo, we should either:

* expose at least the formatting helpers here publically so callers can
  use them.
* allow only a limitted set of headers, maybe we an enum. we can then
  handle formatting for the caller be seeing which enum type was
  provided

what do you think?

> this does not check for duplicates for the ones already set by other
> fields/defaults (e.g. To, From, Content-Type, etc.)
>
> Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
> ---
>  proxmox-sendmail/src/lib.rs | 47 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 47 insertions(+)
>
> diff --git a/proxmox-sendmail/src/lib.rs b/proxmox-sendmail/src/lib.rs
> index db751305..355a84c2 100644
> --- a/proxmox-sendmail/src/lib.rs
> +++ b/proxmox-sendmail/src/lib.rs
> @@ -3,6 +3,7 @@
>  //! and alternative html parts to one or multiple receivers via ``sendmail``.
>  //!
>
> +use std::collections::HashMap;
>  use std::io::Write;
>  use std::process::{Command, Stdio};
>
> @@ -247,6 +248,7 @@ pub struct Mail<'a> {
>      attachments: Vec<Attachment<'a>>,
>      mask_participants: bool,
>      noreply: Option<Recipient>,
> +    additional_headers: HashMap<String, String>,
>  }
>
>  impl<'a> Mail<'a> {
> @@ -265,6 +267,7 @@ impl<'a> Mail<'a> {
>              attachments: Vec::new(),
>              mask_participants: true,
>              noreply: None,
> +            additional_headers: HashMap::new(),
>          }
>      }
>
> @@ -393,6 +396,20 @@ impl<'a> Mail<'a> {
>          self
>      }
>
> +    /// Set an arbitrary header to be sent in addition to the default ones already set up by other
> +    /// methods.
> +    pub fn set_header<S: ToString>(&mut self, name: S, body: S) {
> +        self.additional_headers
> +            .insert(name.to_string(), body.to_string());
> +    }
> +
> +    /// Builder-style method to set an arbitrary header in addition to the default ones already
> +    /// set up by other methods.
> +    pub fn with_header<S: ToString>(mut self, name: S, body: S) -> Self {
> +        self.set_header(name, body);
> +        self
> +    }
> +
>      /// Sends the email. This will fail if no recipients have been added.
>      ///
>      /// Note: An `Auto-Submitted: auto-generated` header is added to avoid triggering OOO and
> @@ -584,6 +601,11 @@ impl<'a> Mail<'a> {
>          let rfc2822_date = proxmox_time::epoch_to_rfc2822(now)
>              .with_context(|| "could not convert epoch to rfc2822 date")?;
>          writeln!(header, "Date: {rfc2822_date}")?;
> +
> +        for (name, body) in &self.additional_headers {
> +            writeln!(header, "{name}: {body}")?;
> +        }
> +
>          header.push_str("Auto-Submitted: auto-generated;\n");
>
>          Ok(header)
> @@ -681,6 +703,31 @@ mod test {
>          assert!(result.is_err());
>      }
>
> +    #[test]
> +    fn additional_headers() {
> +        let mail = Mail::new("Sender", "mail@example.com", "hi", "body")
> +            .with_recipient_and_name("Jane Doe", "j.doe@example.com")
> +            .with_header("Reply-To", "mail@example.com")
> +            .with_header("CC", "cc1@example.com,cc2@example.com");
> +        let body = mail.format_mail(0).expect("could not format mail");
> +
> +        assert_lines_equal_ignore_date(
> +            &body,
> +            r#"Subject: hi
> +From: Sender <mail@example.com>
> +To: Jane Doe <j.doe@example.com>
> +Date: Thu, 01 Jan 1970 01:00:00 +0100
> +Reply-To: mail@example.com
> +CC: cc1@example.com,cc2@example.com
> +Auto-Submitted: auto-generated;
> +Content-Type: text/plain;
> +	charset="UTF-8"
> +Content-Transfer-Encoding: 7bit
> +
> +body"#,
> +        )
> +    }
> +
>      #[test]
>      fn simple_ascii_text_mail() {
>          let mail = Mail::new(

Re: [PATCH proxmox 1/1] sendmail: add additional header map

[Nicolas Frey]

On 6/15/26 3:20 PM, Shannon Sterz wrote:
> On Mon Jun 15, 2026 at 11:20 AM CEST, Nicolas Frey wrote:
>> with corresponding methods to add them.
>>
> 
> generally i like the idea of allowing callers to specify additional
> headers, but i wonder if this is a bit too lenient. usually, we try to
> handle all encoding and formatting for the caller here, so we can deal
> with being in compliance with all rfcs and mail related conventions here
> instead of all call-sites.
> 

Yeah I think it would be best to restrict in such a way that the
caller does not really care about encoding/formatting and it's all
done on the proxmox-sendmail site. Perhaps I should have sent it as an
RFC, because I was very unsure how lax we wanna be here/who needs to
deal with encoding/formatting the headers.

> also this would allow setting headers that are set by proxmox-sendmail
> anyway twice. that's probably not ideal either.

I did have a draft where it just removes those already set somewhere
else, but that felt a bit clunky, so also not ideal

> 
> so imo, we should either:
> 
> * expose at least the formatting helpers here publically so callers can
>   use them.
> * allow only a limitted set of headers, maybe we an enum. we can then
>   handle formatting for the caller be seeing which enum type was
>   provided
> 
> what do you think?
> 

My initial goal was to make it so adding additional headers would not
need another crate bump in the future. Regardless of that, I think a
limited set of headers could work pretty well. I'll try the enum
approach and send a V2 if it looks good, thanks!

--- >8 snip 8< ---

Re: [PATCH proxmox 1/1] sendmail: add additional header map

[Shannon Sterz]

On Mon Jun 15, 2026 at 4:01 PM CEST, Nicolas Frey wrote:
>
>
> On 6/15/26 3:20 PM, Shannon Sterz wrote:
>> On Mon Jun 15, 2026 at 11:20 AM CEST, Nicolas Frey wrote:
>>> with corresponding methods to add them.
>>>
>>
>> generally i like the idea of allowing callers to specify additional
>> headers, but i wonder if this is a bit too lenient. usually, we try to
>> handle all encoding and formatting for the caller here, so we can deal
>> with being in compliance with all rfcs and mail related conventions here
>> instead of all call-sites.
>>
>
> Yeah I think it would be best to restrict in such a way that the
> caller does not really care about encoding/formatting and it's all
> done on the proxmox-sendmail site. Perhaps I should have sent it as an
> RFC, because I was very unsure how lax we wanna be here/who needs to
> deal with encoding/formatting the headers.

maybe, doesn't make too much of a difference now tho ;)

>> also this would allow setting headers that are set by proxmox-sendmail
>> anyway twice. that's probably not ideal either.
>
> I did have a draft where it just removes those already set somewhere
> else, but that felt a bit clunky, so also not ideal

hm that feels like it could easily lead to misunderstanding by the
caller on what takes priority. i don't think that's ideal either.

>>
>> so imo, we should either:
>>
>> * expose at least the formatting helpers here publically so callers can
>>   use them.
>> * allow only a limitted set of headers, maybe we an enum. we can then
>>   handle formatting for the caller be seeing which enum type was
>>   provided
>>
>> what do you think?
>>
>
> My initial goal was to make it so adding additional headers would not
> need another crate bump in the future. Regardless of that, I think a
> limited set of headers could work pretty well. I'll try the enum
> approach and send a V2 if it looks good, thanks!

fair enough. in that case we could consider a "generic" enum variant
that gives the caller no guarantees for formatting or (de-)duplication
as an escape hatch. in that case it is then at least clear to the caller
that they are talking full responsibility for the "correctness" of
adding such a header.

tho i think starting without such an escape hatch and only adding it
once we need it is probably preferable.

superseded: [PATCH proxmox 1/1] sendmail: add additional header map

[Nicolas Frey]

Superseded-by: https://lore.proxmox.com/pve-devel/20260616095402.83702-1-n.frey@proxmox.com/T/#u