message

Namespace: global/message

Inspect incoming messages.

fn mail_str

fn mail_str(ctx: State<StatefulCtxReceived>) -> Result<String>

Description

Get a copy of the whole email as a string.

Effective smtp stage

preq and onwards.

Example

#{
    postq: [
       action "display email content" || log("trace", `email content: ${msg::mail()}`),
    ]
}

get mail

fn get mail(ctx: State<StatefulCtxReceived>) -> RwLock<Mail>>>

Description

Get a reference to the email.

fn to_debug

fn to_debug(mail: RwLock<Mail>>) -> String

Description

Return a debug string of the email.

fn has_header

fn has_header(ctx: State<StatefulCtxReceived>, header: String) -> Result<bool>

Description

Checks if the message contains a specific header.

Args

• header - the name of the header to search.

Effective smtp stage

All of them, although it is most useful in the preq stage because the email is received at this point.

Examples

// Message example.
"X-My-Header: foo\r\n",
"Subject: Unit test are cool\r\n",
"\r\n",
"Hello world!\r\n",
#{
  preq: [
    rule "check if header exists" || {
      if msg::has_header("X-My-Header") && msg::has_header(identifier("Subject")) {
        state::accept();
      } else {
        state::deny();
      }
    }
  ]
}

fn count_header

fn count_header(ctx: State<StatefulCtxReceived>, header: String) -> int>

Description

Count the number of headers with the given name.

Args

• header - the name of the header to count.

Return

• number - the number headers with the same name.

Effective smtp stage

All of them, although it is most useful in the preq stage because this is when the email body is received.

Examples

"X-My-Header: foo\r\n",
"X-My-Header: bar\r\n",
"X-My-Header: baz\r\n",
"Subject: Unit test are cool\r\n",
"\r\n",
"Hello world!\r\n",
#{
  preq: [
    rule "count_header" || {
      state::accept(`250 count is ${msg::count_header("X-My-Header")} and ${msg::count_header(identifier("Subject"))}`);
    }
  ]
}

fn get_header

fn get_header(ctx: State<StatefulCtxReceived>, header: String) -> ?>

Description

Get a specific header from the incoming message.

Args

• header - the name of the header to get.

Return

• string - the header value if the header was found.
• () - a rhai unit if the header was not found.

Effective smtp stage

All of them, although it is most useful in the preq stage because this is when the email body is received.

Examples

X-My-Header: 250 foo
Subject: Unit test are cool

Hello world!
; // .eml ends here

let rules = r#"
#{
  preq: [
    rule "get_header" || {
      if msg::get_header("X-My-Header") != "250 foo"
        || msg::get_header(identifier("Subject")) != "Unit test are cool" {
        state::deny();
      } else {
        state::accept(`${msg::get_header("X-My-Header")} ${msg::get_header(identifier("Subject"))}`);
      }
    }
  ]
}

fn get_all_headers

fn get_all_headers(ctx: State<StatefulCtxReceived>) -> Array>
fn get_all_headers(ctx: State<StatefulCtxReceived>, name: String) -> Array>

Description

Get a list of all headers.

Args

• header - the name of the header to search. (optional, if not set, returns every header)

Return

• array - all of the headers found in the message.

Effective smtp stage

All of them, although it is most useful in the preq stage because this is when the email body is received.

Examples

X-My-Header: 250 foo
Subject: Unit test are cool

Hello world!
; // .eml ends here

#{
  preq: [
    rule "display headers" || {
        log("info", `all headers: ${msg::get_all_headers()}`);
        log("info", `all "Return-Path" headers: ${msg::get_all_headers("Return-Path")}`);
    }
  ]
}

fn get_header_untouched

fn get_header_untouched(ctx: State<StatefulCtxReceived>, name: String) -> Array>

Description

Get a list of all headers of a specific name with it's name and value separated by a column.

Args

• header - the name of the header to search.

Return

• array - all header values, or an empty array if the header was not found.

Effective smtp stage

All of them, although it is most useful in the preq stage because this is when the email body is received.

Examples

X-My-Header: 250 foo
Subject: Unit test are cool

Hello world!
; // .eml ends here

#{
    postq: [
        action "display return path" || {
            // Will display "Return-Path: value".
            log("info", msg::get_header_untouched("Return-Path"));
        }
    ],
}

fn append_header

fn append_header(ctx: State<StatefulCtxReceived>, name: String, body: String) -> Result<()>

Description

Add a new header **at the end** of the header list in the message.

Args

• header - the name of the header to append.
• value - the value of the header to append.

Effective smtp stage

All of them. Even though the email is not received at the current stage, vsmtp stores new headers and will add them on top of the ones received once the preq stage is reached.

Examples

"X-My-Header: 250 foo\r\n",
"Subject: Unit test are cool\r\n",
"\r\n",
"Hello world!\r\n",
#{
  preq: [
    rule "append_header" || {
      msg::append_header("X-My-Header-2", "bar");
      msg::append_header("X-My-Header-3", identifier("baz"));
    }
  ]
}

fn prepend_header

fn prepend_header(ctx: State<StatefulCtxReceived>, header: String, value: String) -> Result<()>

Description

Add a new header on top all other headers in the message.

Args

• header - the name of the header to prepend.
• value - the value of the header to prepend.

Effective smtp stage

All of them. Even though the email is not received at the current stage, vsmtp stores new headers and will add them on top of the ones received once the preq stage is reached.

Examples

"X-My-Header: 250 foo\r\n",
"Subject: Unit test are cool\r\n",
"\r\n",
"Hello world!\r\n",
#{
  preq: [
    rule "prepend_header" || {
      msg::prepend_header("X-My-Header-2", "bar");
      msg::prepend_header("X-My-Header-3", identifier("baz"));
    }
  ]
}

fn set_header

fn set_header(ctx: State<StatefulCtxReceived>, header: String, value: String) -> Result<()>

Description

Replace an existing header value by a new value, or append a new header to the message.

Args

• header - the name of the header to set or add.
• value - the value of the header to set or add.

Effective smtp stage

All of them. Even though the email is not received at the current stage, vsmtp stores new headers and will add them on top to the ones received once the preq stage is reached.

Be aware that if you want to set a header value from the original message, you must use set_header in the preq stage and onwards.

Examples

"Subject: The initial header value\r\n",
"\r\n",
"Hello world!\r\n",
#{
  preq: [
    rule "set_header" || {
      msg::set_header("Subject", "The header value has been updated");
      msg::set_header("Subject", identifier("The header value has been updated again"));
      state::accept(`250 ${msg::get_header("Subject")}`);
    }
  ]
}

fn rename_header

fn rename_header(ctx: State<StatefulCtxReceived>, old: String, new: String) -> Result<()>

Description

Replace an existing header name by a new value.

Args

• old - the name of the header to rename.
• new - the new new of the header.

Effective smtp stage

All of them, although it is most useful in the preq stage because this is when the email body is received.

Examples

"Subject: The initial header value\r\n",
"\r\n",
"Hello world!\r\n",

#{
  preq: [
    rule "rename_header" || {
      msg::rename_header("Subject", "bob");
      if msg::has_header("Subject") { return state::deny(); }

      msg::rename_header("bob", identifier("Subject"));
      if msg::has_header("bob") { return state::deny(); }

      msg::rename_header(identifier("Subject"), "foo");
      if msg::has_header("Subject") { return state::deny(); }

      msg::rename_header(identifier("foo"), identifier("Subject"));
      if msg::has_header("foo") { return state::deny(); }

      state::accept(`250 ${msg::get_header("Subject")}`);
    }
  ]
}

fn rm_header

fn rm_header(ctx: State<StatefulCtxReceived>, header: String) -> Result<bool>

Description

Remove an existing header from the message.

Args

• header - the name of the header to remove.

Return

• a boolean value, true if a header has been removed, false otherwise.

Effective smtp stage

All of them, although it is most useful in the preq stage because this is when the email body is received.

Examples

"Subject: The initial header value\r\n",
"\r\n",
"Hello world!\r\n",
#{
  preq: [
    rule "remove_header" || {
      msg::rm_header("Subject");
      if msg::has_header("Subject") { return state::deny(); }

      msg::prepend_header("Subject-2", "Rust is good");
      msg::rm_header(identifier("Subject-2"));

      msg::prepend_header("Subject-3", "Rust is good !!!!!");

      state::accept(`250 ${msg::get_header("Subject-3")}`);
    }
  ]
}

fn rw_mail_from

fn rw_mail_from(ctx: State<StatefulCtxReceived>, new_addr: String) -> Result<()>

Description

Change the sender's address in the `From` header of the message.

Args

• new_addr - the new sender address to set.

Effective smtp stage

preq and onwards.

Examples

#{
    preq: [
       action "replace sender" || msg::rw_mail_from("john.server@example.com"),
    ]
}

fn rw_rcpt

fn rw_rcpt(ctx: State<StatefulCtxReceived>, old_addr: String, new_addr: String) -> Result<()>

Description

Replace a recipient by an other in the `To` header of the message.

Args

• old_addr - the recipient to replace.
• new_addr - the new address to use when replacing old_addr.

Effective smtp stage

preq and onwards.

Examples

#{
    preq: [
       action "rewrite recipient" || msg::rw_rcpt("john.doe@example.com", "john-mta@example.com"),
    ]
}

fn add_rcpt

fn add_rcpt(ctx: State<StatefulCtxReceived>, new_addr: String) -> Result<()>

Description

Add a recipient to the `To` header of the message.

Args

• addr - the recipient address to add to the To header.

Effective smtp stage

preq and onwards.

Examples

#{
    preq: [
       action "update recipients" || msg::add_rcpt("john.doe@example.com"),
    ]
}

fn rm_rcpt

fn rm_rcpt(ctx: State<StatefulCtxReceived>, addr: String) -> Result<()>

Description

Remove a recipient from the `To` header of the message.

Args

• addr - the recipient to remove to the To header.

Effective smtp stage

preq and onwards.

Examples

#{
    preq: [
       action "update recipients" || msg::rm_rcpt("john.doe@example.com"),
    ]
}

fn body_string

fn body_string(ctx: State<StatefulCtxReceived>) -> Result<String>

Description

Get the body of the email as a string.

Effective smtp stage

preq and onwards.

Examples

TODO: