---
name: "Net::IMAP::SimpleX"
section: "3pm"
platform: "linux"
package: "perl-net-imap-simple"
version: "1.2212-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Net::IMAP::SimpleX"
---

# Net::IMAP::SimpleX(3pm)

Addons for Net::IMAP::Simple

## NAME

Net::IMAP::SimpleX - Addons for Net::IMAP::Simple

## SYNOPSIS

```
    use strict;
    use warnings;
    use Net::IMAP::SimpleX;
```

Net::IMAP::SimpleX uses Net::IMAP::Simple as a base so the object creation is the same as it is for the ancestor:

```
    my $imap = Net::IMAP::SimpleX->new('imap.example.com') ||
       die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\n";
    $imap->select("INBOX");
```

Net::IMAP::SimpleX is a collection of handy methods that are not simple, require Parse::RecDescent, or are experimental.

## DESCRIPTION

This module adds some useful, yet not so simple, extensions on top of Net::IMAP::Simple.

## METHODS

- new

  For details on the invocation, read Net::IMAP::Simple.

- body\_summary

  Typical invocations will take this overall shape.

  ```
      # get an object representation of the message body
      my $summary = $imap->body_summary($message_number);
      # multipart message
      if ($summary->has_parts) {
          for my $subpart ($summary->parts) {
              if ($subpart->has_parts) { ... }
              # examine the message part
              my @attr = map { $subpart->$_ } qw/content_type encoding encoded_size/;
              # fetch the raw message part
              my $subpart_body = $imap->get($message_number, $subpart->part_number);
          }
      } else {
          my $body = $summary->body;
          my @attr = map { $body->$_ } qw/content_type encoding encoded_size/
      }
  ```

  This method returns a simple object that contains a representation of the body of a message.  The object is built by a Parse::RecDescent parser using the output of an IMAP *fetch body* command.  The parser uses the formal syntax as defined by RFC3501 \<http://tools.ietf.org/html/rfc3501#section-9\>.

  ```
      my $body = $summary->body;
      my @attr = map { $body->$_ } qw/
          content_description
          encoded_size
          charset
          content_type
          part_number
          format
          id
          encoding
      /;
  ```

  For multipart messages, the object contains sub-objects for each message part, accessible via the **parts()** method and inspected via the **has\_parts()** method. The type method describes the type of multipart (such as mixed or alternative). The parts method returns a list of sub parts, which themselves may have subparts, and so on.

  An example of a multipart, alternative message with a text body and an html version of the body would looke something like:

  ```
      if ($summary->has_parts) {
          if ($summary->type eq 'alternative') {
              my ($html) = grep { $_->content_type eq 'text/html' } $summary->parts;
          }
      }
  ```

  A really complex, multipart message could look something like this:

  ```
      if ($summary->has_parts && $summary->type eq 'mixed') {
          for my $part ($summary->parts) {
              if ($part->has_parts && $part->type eq 'mixed') { ... }
              ...
          }
      }
  ```

- fetch

  The fetch command returns the various parts of messages that users request.  It is fairly complicated (following RFC3501 using a grammar/parser), but there are some basic patterns that it follows.

  ```
      my $res  =$imap->fetch('30:32' => 'UID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS')
      # $res = {
      #   30 => {
      #           "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 -0400\r\n\r\n",
      #           "FLAGS" => ["\\Flagged", "\\Seen"],
      #           "UID" => 58890,
      #         },
      #   31 => {
      #           "BODY[HEADER.FIELDS (DATE)]" => "Date: Wed, 21 Jul 2010 09:09:04 -0400\r\n\r\n",
      #           "FLAGS" => ["\\Seen"],
      #           "UID" => 58891,
      #         },
      #   32 => {
      #           "BODY[HEADER.FIELDS (DATE)]" => "Date: Sat, 24 Jul 2010 05:12:06 -0700\r\n\r\n",
      #           "FLAGS" => ["\\Seen"],
      #           "UID" => 58892,
      #         },
      # }
  ```

  So-called "parenthized" lists will be returned as an array (see `"FLAGS"`) but nearly everything else will come back as strings.  This includes parenthized queries.  Take `"BODY.PEAK[HEADER.FIELDS (DATE FROM SUBJECT)]"`), for example. The result would come back as the RFC822 header lines (as the above `"Date: Sun,` `..."` has done).

  For more information about the different types of queries, see RFC3501.  There's a surprising number of things that can be queried.

- uidfetch

  This is roughly the same thing as the `fetch()` method above, but the query runs on UIDs instead of sequence numbers.  The keys of the `$res` are still the sequence numbers though.

  ```
      my $res  =$imap->fetch('58890' => 'UID BODY.PEEK[HEADER.FIELDS (DATE)] FLAGS')
      # $res = {
      #   30 => {
      #           "BODY[HEADER.FIELDS (DATE)]" => "Date: Sun, 18 Jul 2010 20:54:48 -0400\r\n\r\n",
      #           "FLAGS" => ["\\Flagged", "\\Seen"],
      #           "UID" => 58890,
      #         },
      #   ...
  ```

## AUTHOR

- INITIAL AUTHOR

  Jason Woodward `"<woodwardj@jaos.org>"`

- ADDITIONAL CONTRIBUTIONS

  Paul Miller `"<jettero@cpan.org>"`  \[***fetch()***\]

## COPYRIGHT

Copyright (c) 2010 Jason Woodward

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

## LICENSE

This module is free software.  You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

## BUGS

\<https://rt.cpan.org/Dist/Display.html?Queue=Net-IMAP-Simple\>

## SEE ALSO

perl, Net::IMAP::Simple, Parse::RecDescent