#### 5.6.2 External Tests ¶

Test: list `[comparator] [match-type] [ :delim delimiters(string) ] headers(string-list) keys(string-list)` ¶

  Synopsis:

      require "test-list";
      if list args
        {
           ...
        }

  Description: The `list` test evaluates to true if any of headers matches any key from keys. Each header is regarded as containing a list of keywords. By default, comma is assumed as list separator. This can be overridden by specifying the `:delim` tag, whose value is a string consisting of valid list delimiter characters.

  Example:

  This test can be used in conjunction with the `spamd` test described above:

      require ["fileinto", "test-spamd", "test-list"];

      if spamd :host 127.0.0.1 :port 3333
        {
           if list :matches :delim " ,"
                   "X-Spamd-Keywords" [ "HTML_*", "FORGED_*" ]
             {
                fileinto "~/mail/spam";
             }
           else
             {
                discard;
             }
        }

Test: numaddr `[:over | :under] header-names(string-list) count(number)` ¶

  Synopsis:

      require "test-numaddr";
      ...
      if numaddr args
        {
          ...
        }

  Description: This test is provided as an example of loadable extension tests. You must use ‘`require "test-numaddr"`’ statement before actually using it.

  The `numaddr` test counts Internet addresses in structured headers that contain addresses. It returns true if the total number of addresses satisfies the requested relation.

  If the tagged argument is ‘`:over`’ and the number of addresses is greater than count, the test is true; otherwise, it is false.

  If the tagged argument is ‘`:under`’ and the number of addresses is less than count, the test is true; otherwise, it is false.

  If the tagged argument is not given, ‘`:over`’ is assumed.

Test: pipe `[:envelope] [:header] [:body] [:exit code(number)] [:signal code(number)] command(string)` ¶

  Synopsis:

      require "test-pipe";

      if pipe command
        {
          ...
        }

  Description: The `pipe` test executes a shell command specified by its argument and pipes the entire message (including envelope) to its standard input. When given, tags `:envelope`, `:header`, and `:body` control what parts of the message to pipe to the command.

  In the absence of the `:exit` tag, the test returns true if the command exits with code 0. If `:exit` is given, the test returns true if the command exits with code equal to its argument.

  The `:signal` tag determines the result of the test in case if the program exits on signal. By default, the test returns false. If `:signal` is given and the number of signal which caused the program to terminate matches its argument, the test returns true.

Test: spamd `[:host tcp-host(string)] [:port tcp-port(number)] [:socket unix-socket(string)] [:user name(string)] [:over | :under limit(string)]` ¶

  Synopsis:

      require "test-spamd";
      ...
      if spamd args
        {
          # This is spam
          ...
        }

  Description: This test is an interface to SpamAssassin filter. It connects to the `spamd` daemon using connection parameters specified by tagged arguments `:host` and `:port` (if the daemon is listening on an INET socket), or `:socket` (if the daemon is listening on a UNIX socket) and returns true, if SpamAssassin qualifies the message as spam. Tagged argument limit alters the default behavior. Its value is a string representation of a floating point number. If the tag `:over` is used, then the test returns true if the spam score returned from SpamAssassin is greater than limit. Otherwise, if `:under` is used, the test returns true if the spam score is less than limit. The comparison takes into account three decimal digits.

  Tagged argument `:user` selects a specific user profile. If it is not given, the user name is determined using the effective UID.

  Before returning, the `spamd` test adds the following headers to the message:

  X-Spamd-Status

    ‘`YES`’ or ‘`NO`’, depending on whether the message is qualified as spam or ham.

  X-Spamd-Score

    Actual spam score value.

  X-Spamd-Threshold

    Spam score threshold, as configured in SpamAssassin settings.

  X-Spamd-Keywords

    Comma-separated list of keywords, describing the spam checks that succeeded for this message.

  Example:

      request "test-spamd";

      if spamd :host 127.0.0.1 :port 3333
        {
           discard;
        }

Test: timestamp `[:before | :after] header(string) date(string)` ¶

  Synopsis:

      require "test-timestamp";

      if timestamp arg
        {
           ...
        }

  Description: The `timestamp` test compares the value of a structured date header field (header) with the given date (date).

  If the tagged argument is `:after` and the date from the header is after the specified date the result is true, otherwise, if the header date is before the given date, the result is false.

  If the tagged argument is `:before` and the date from the header is before the specified date the result is true, otherwise, if the header date is after the given date, the result is false.

  If no tagged argument is supplied, `:after` is assumed.

  Almost any date format is understood. See Date Input Formats, for a detailed information on date formats.

  Example:

  The test below succeeds if the date in ‘`X-Expire-Timestamp`’ header is more than 5 days older than the current date:

      require "test-timestamp";

      if timestamp :before "X-Expire-Timestamp" "now - 5 days"
        {
           discard;
        }

Test: uidnew `[ :db dbname(string) ] [ :mailbox mbname(string) ]` ¶

  Synopsis:

      if uidnew
        {
           ...
        }

  Description: This test evaluates to true if the current message has never been processed before. It is designed for use in cases where the processed messages are retained in the mailbox (see keep).

  For each processed mailbox, the test keeps its state, which consists of the mailbox uidvalidity and last processed UID. The states are stored in the GDBM database `.uidnew.db` in the user home directory. The name and type of the database file can be changed using the `:db` tagged argument. Its value is either the pathname to the database file, or its URL. The tilde (`~`) character followed by the slash appearing at the start of the pathname expands to the user home directory. A tilde followed by the username and a slash, expands to the home directory of that user. For example:

      if uidnew :db gdbm://~/uidstate.db
        {
           fileinto "store";
           keep;
        }

  The `:mailbox` agrument supplies the key value under which the mailbox state is stored. By default, full URL of the current mailbox is used. This argument can be useful when the mailbox name is not available, e.g. if processing a single message (`sieve -f -`).