---
name: "Mail::SpamAssassin::ArchiveIterator"
section: "3pm"
platform: "linux"
package: "spamassassin"
version: "4.0.2-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Mail::SpamAssassin::ArchiveIterator"
---

# Mail::SpamAssassin::ArchiveIterator(3pm)

find and process messages one at a time

## NAME

Mail::SpamAssassin::ArchiveIterator - find and process messages one at a time

## SYNOPSIS

```
  my $iter = Mail::SpamAssassin::ArchiveIterator->new(
    {
      'opt_max_size' => 500 * 1024,  # 0 implies no limit
      'opt_cache' => 1,
    }
  );
  $iter->set_functions( \&wanted, sub { } );
  eval { $iter->run(@ARGV); };
  sub wanted {
    my($class, $filename, $recv_date, $msg_array) = @_;
    ...
  }
```

## DESCRIPTION

The Mail::SpamAssassin::ArchiveIterator module will go through a set of mbox files, mbx files, and directories (with a single message per file) and generate a list of messages.  It will then call the `"wanted_sub"` and `"result_sub"` functions appropriately per message.

## METHODS

- $item = Mail::SpamAssassin::ArchiveIterator-\>new( \[ { opt =\> val, ... } \] )

  Constructs a new `"Mail::SpamAssassin::ArchiveIterator"` object.  You may pass the following attribute-value pairs to the constructor.  The pairs are optional unless otherwise noted.

  - opt\_max\_size

    A value of option *opt\_max\_size* determines a limit (number of bytes) beyond which a message is considered large and is skipped by ArchiveIterator.

    A value 0 implies no size limit, all messages are examined. An undefined value implies a default limit of 500 KiB.

  - opt\_all

    Setting this option to true implicitly sets *opt\_max\_size* to 0, i.e. no limit of a message size, all messages are processes by ArchiveIterator. For compatibility with SpamAssassin versions older than 3.4.0 which lacked option *opt\_max\_size*.

  - opt\_scanprob

    Randomly select messages to scan, with a probability of N, where N ranges from 0.0 (no messages scanned) to 1.0 (all messages scanned).  Default is 1.0.

    This setting can be specified separately for each target.

  - opt\_before

    Only use messages which are received after the given time\_t value. Negative values are an offset from the current time, e.g. -86400 = last 24 hours; or as parsed by Time::ParseDate (e.g. '-6 months')

    This setting can be specified separately for each target.

  - opt\_after

    Same as opt\_before, except the messages are only used if after the given time\_t value.

    This setting can be specified separately for each target.

  - opt\_want\_date

    Set to 1 (default) if you want the received date to be filled in in the `"wanted_sub"` callback below.  Set this to 0 to avoid this; it's a good idea to set this to 0 if you can, as it imposes a performance hit.

  - opt\_skip\_empty\_messages

    Set to 1 if you want to skip corrupt, 0-byte messages.  The default is 0.

  - opt\_cache

    Set to 0 (default) if you don't want to use cached information to help speed up ArchiveIterator.  Set to 1 to enable.  This setting requires `"opt_cachedir"` also be set.

  - opt\_cachedir

    Set to the path of a directory where you wish to store cached information for `"opt_cache"`, if you don't want to mix them with the input files (as is the default).  The directory must be both readable and writable.

  - wanted\_sub

    Reference to a subroutine which will process message data.  Usually set via **set\_functions()**.  The routine will be passed 5 values: class (scalar), filename (scalar), received date (scalar), message content (array reference, one message line per element), and the message format key ('f' for file, 'm' for mbox, 'b' for mbx).

    Note that if `"opt_want_date"` is set to 0, the received date scalar will be undefined.

  - result\_sub

    Reference to a subroutine which will process the results of the wanted\_sub for each message processed.  Usually set via **set\_functions()**. The routine will be passed 3 values: class (scalar), result (scalar, returned from wanted\_sub), and received date (scalar).

    Note that if `"opt_want_date"` is set to 0, the received date scalar will be undefined.

  - scan\_progress\_sub

    Reference to a subroutine which will be called intermittently during the 'scan' phase of the mass-check.  No guarantees are made as to how frequently this may happen, mind you.

  - opt\_from\_regex

    This setting allows for flexibility in specifying the mbox format From separator.

    It defaults to the regular expression:

    /^From \\S+  ?(\\S\\S\\S \\S\\S\\S .?\\d .?\\d:\\d\\d:\\d\\d \\d{4}\|.?\\d-\\d\\d-\\d{4}\_\\d\\d:\\d\\d:\\d\\d\_)/

    Some SpamAssassin programs such as sa-learn will use the configuration option  'mbox\_format\_from\_regex' to override the default regular expression.

- set\_functions( \\&wanted\_sub, \\&result\_sub )

  Sets the subroutines used for message processing (wanted\_sub), and result reporting.  For more information, see ***new()*** above.

- run ( @target\_paths )

  Generates the list of messages to process, then runs each message through the configured wanted subroutine.

  Compressed files are detected and uncompressed automatically regardless of file extension.  Supported formats are `"gzip"`, `"bzip2"`, `"xz"`, `"lz4"`, `"lzip"`, `"lzo"`.  Gzip is uncompressed via IO::Zlib module, others use their specific command line tool (bzip2/xz/lz4/lzip/lzop).  Compressed mailbox/mbox files are not supported.

  The target\_paths array is expected to be either one element per path in the following format: `"class:format:raw_location"`, or a hash reference containing key-value option pairs and a 'target' key with a value in that format.

  The key-value option pairs that can be used are: opt\_scanprob, opt\_after, opt\_before.  See the constructor method's documentation for more information on their effects.

  **run()** returns 0 if there was an error (can't open a file, etc,) and 1 if there were no errors.

  - class

    Either 'h' for ham or 's' for spam.  If the class is longer than 1 character, it will be truncated.  If blank, 'h' is default.

  - format

    Specifies the format of the raw\_location.  `"dir"` is a directory whose files are individual messages, `"file"` a file with a single message, `"mbox"` an mbox formatted file, or `"mbx"` for an mbx formatted directory.

    `"detect"` can also be used.  This assumes `"mbox"` for any file whose path contains the pattern `"/\.mbox/i"`, `"file"` anything that is not a directory, or `"directory"` otherwise.

  - raw\_location

    Path to file or directory.  File globbing is allowed using the standard csh-style globbing (see `"perldoc -f glob"`).  `"~"` at the front of the value will be replaced by the `"HOME"` environment variable.  Escaped whitespace is protected as well.

    **NOTE:** `"~user"` is not allowed.

    **NOTE 2:** `"-"` is not allowed as a raw location.  To have ArchiveIterator deal with STDIN, generate a temp file.

## SEE ALSO

**Mail::SpamAssassin**(3) **spamassassin**(1) **mass-check**(1)