Net::I...:Simple(3pm)

📦
version 1.2211 · 5 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

🎀 NAME 🎀

Okay bestie, listen: Net::IMAP::Simple is a Perl extension for simple IMAP account handling. That’s the whole assignment. It’s giving “I just want to talk to my IMAP server without a whole dramatic saga,” and honestly? Iconic. 💖

🌈 SYNOPSIS 🌈

Here’s the vibe in code form — literally the whole little group-chat intro:

use strict;
use warnings;
use Net::IMAP::Simple;
use Email::Simple;

# Create the object
my $imap = Net::IMAP::Simple->new('imap.example.com') ||
   die "Unable to connect to IMAP: $Net::IMAP::Simple::errstr\n";

# Log on
if(!$imap->login('user','pass')){
    print STDERR "Login failed: " . $imap->errstr . "\n";
    exit(64);
}

# Print the subject's of all the messages in the INBOX
my $nm = $imap->select('INBOX');

for(my $i = 1; $i <= $nm; $i++){
    if($imap->seen($i)){
        print "*";
    } else {
        print " ";
    }

    my $es = Email::Simple->new(join '', @{ $imap->top($i) } );

    printf("[%03d] %s\n", $i, $es->header('Subject'));
}

$imap->quit;

🦋 DESCRIPTION 🦋

This module is a simple way to access IMAP accounts. No cap — it’s literally the low-drama route to IMAP. ✨

✨ OBJECT CREATION METHOD ✨

my $imap = Net::IMAP::Simple->new( $server [ :port ]);

# OR

my $imap = Net::IMAP::Simple->new( $server [, option_name => option_value ] );

💅 new 💅

This class method constructs a new Net::IMAP::Simple object. It takes one required parameter — the server to connect to — plus additional optional parameters. 🫶

The server parameter may specify just the server, or both the server and port number. To specify an alternate port, separate it from the server with a colon (:), like example.com:5143.

On success an object is returned. On failure, nothing is returned and an error message is set to $Net::IMAP::Simple.

See “PREAUTH” below for a special hostname invocation that doesn’t use Sockets (internally).

Options are provided as a hash to new():

  • port => int — assign the port number (default: 143).
  • timeout => int — connection timeout in seconds (default: 90).
  • retry => int — attempt to retry the connection attempt (x) times before giving up (default: 1).
  • retry_delay => int — wait (x) seconds before retrying a connection attempt (default: 5).
  • use_v6 => BOOL — if set to true, attempt to use IPv6 sockets rather than IPv4 sockets. This option requires the IO::Socket::INET6 module.
  • use_ssl => BOOL — if set to true, attempt to use IO::Socket::SSL sockets rather than vanilla sockets. Note that no attempt is made to check the certificate validity by default. This is terrible personal security but matches the previous behavior of this module. Please consider using find_ssl_defaults below. This option requires the IO::Socket::SSL module.
  • ssl_version => version — this should be one or more of the following (space separated): SSLv3 SSLv2 TLSv1. If you specify, for example, SSLv3 SSLv2, then IO::Socket::SSL will attempt auto negotiation. At the time of this writing, the default string was v3/v2 auto negotiation — it may have changed by the time you read this. ⚠️ Warning: setting this will also set use_ssl.
  • find_ssl_defaults => [] — looks in some standard places for CA certificate libraries and, if found, sets reasonable defaults along the lines of the following:
ssl_options => [ SSL_ca_path => "/etc/ssl/certs/",
    SSL_verify_mode => IO::Socket::SSL::SSL_VERIFY_PEER() ]
⚠️ Warning: setting this will also set use_ssl.
  • ssl_options => [] — you may provide your own IO::Socket::SSL options if you desire to do so. It is completely overridden by find_ssl_defaults above.
  • bindaddr => str — assign a local address to bind.
  • use_select_cache => BOOL — enable select() caching internally.
  • select_cache_ttl => int — the number of seconds to allow a select cache result live before running $imap->select() again.
  • debug => BOOL | \*HANDLE | warn | file:name — enable debugging output. If \*HANDLE is a valid file handle, debugging will be written to it. If it is the string warn, then the debugging will be written using the warn command. If it is a string of the form file:name, then the named file will be opened for append and the debugs written to it. Otherwise debugging will be written to STDOUT.
  • readline_callback => CODE — you may choose to pass a callback function for the purpose of pre-processing lines before they are handed to the rest of the Net::IMAP::Simple internals. This can be handy for animating a spinner or modifying the IMAP behavior.

🔐 PREAUTH 🔐

Rather than passing a port number and issuing a login, in some situations it may be convenient to authenticate with (for example) ssh and simply invoke (for example) dovecot by hand.

If the server name starts with cmd:, then Net::IMAP::Simple will issue the command rather than building sockets. This is a typical setup:

my $cmd = "ssh -C mailhost dovecot --exec-mail imap";
my $imap = Net::IMAP::Simple->new("cmd:$cmd");
 # $imap->login(); ... don't need this

my $number_of_messages = $imap->select("INBOX");

🌸 METHODS 🌸

🧚 starttls 🧚

$imap->starttls;

If you start an IMAP session and wish to upgrade to SSL later, you can use this function to start TLS. This function will try to require IO::Socket::SSL and Net::SSLeay at runtime. 💫

🔑 login 🔑

my $inbox_msgs = $imap->login($user, $passwd);

This method takes two required parameters, a username and password. This pair is authenticated against the server. If authentication is successful, TRUE (1) will be returned.

Nothing is returned on failure and the errstr() error handler is set with the error message.

📬 status 📬

my $num_messages                     = $imap->status($folder);
my ($unseen, $recent, $num_messages) = $imap->status($folder);

Issue a STATUS command. The STATUS command counts messages without altering the state of the named (optionally) mailbox. It returns either the number of messages, or the number of unseen messages, recent, and the total number of messages.

$folder is an optional argument. status() will use the current mailbox or INBOX if the $folder argument is not provided.

This method does not use caching.

This method can also query custom status values. The first argument to the function (if any) is assumed to be the folder name, so the folder argument is required when trying to query custom status values.

my ($f1, $f2) = $imap->status($folder, qw(f1 f2));
my $f2        = $imap->status($folder, qw(f1 f2));

🆕 uidnext 🆕

my $uidnext = $imap->uidnext($folder);

Return the UIDNEXT value for a mailbox. The $folder argument is optional. This is really just an alias for

my $uidnext = $imap->status($folder, qw(uidnext));

with the mild difference that it can compute the folder argument for you. 💅

🪪 uidvalidity 🪪

my $uidvalidity = $imap->uidnext($folder);

Return the UIDVALIDITY value for a mailbox. The $folder argument is optional. This is also an alias for the status call like uidnext() above.

🆔 uid 🆔

This function is actually an alias for $imap->uidsearch($msg_range).

my($uid)= $imap->uid($msgno);
my @uid = $imap->uid($msg_range); # eg 4:14  or 15,4,14

Return the UID value(s) for a message. These unique IDs must stay the same during the session and should stay the same between sessions. Whether they stay the same depends on the UIDVALIDITY value; see above and RFC3501.

⚠️ Warning: although you might think @uid should contain the UIDs for 15, then 4, then 14 in the example above, most IMAP servers seem to return the UIDs in increasing order. Normally the sequence numbers are in increasing order also, so it all matches up.
my ($uid4, $uid14, $uid15) = $imap->uid("15,4,14"); # warning

One final note: this gives the size of the search match, not the uid like you might expect:

my $uid_search_result_list_size = $imap->uid('3'); # probably always 1

🔢 seq 🔢

my $seq = $imap->seq($uids);
my @seq = $imap->seq($uids); # eg 58888:58900

Rather like uid() above, but maps uids to sequence numbers. 🎯

📂 select 📂

my $num_messages = $imap->select($folder);

Selects a folder named in the single required parameter. The number of messages in that folder is returned on success. On failure, nothing is returned and the errstr() error handler is set with the error message.

👀 examine 👀

This is very nearly a synonym for select(). The only real difference is that the EXAMINE command is sent to the server instead of SELECT. Net::IMAP::Simple is otherwise unaware of the read-only-ness of the mailbox.

🚪 close 🚪

$imap->close;

Un-selects the current mailbox, leaving no mailbox selected.

💌 messages 💌

print "Messages in Junk Mail -- " . $imap->messages("INBOX.Junk Mail") .  "\n";

This method is an alias for $imap->select.

🚩 flags 🚩

print "Available server flags: " . join(", ", $imap->flags) . "\n";

This method accepts an optional folder name and returns the current available server flags as a list, for the selected folder. If no folder name is provided, the last folder $imap->select'ed will be used.

This method uses caching.

🪄 separator 🪄

Returns the folder separator (technically “hierarchy separator”, rfc3501§6.3.8) for the server.

🕐 recent 🕐

print "Recent messages value: " . $imap->recent . "\n";

This method accepts an optional folder name and returns the RECENT value provided during a SELECT result set. If no folder name is provided, the last folder $imap->select'ed will be used.

This method uses caching.

See also: search.

🙈 unseen 🙈

print "Unseen messages value: " . $imap->unseen . "\n";

This method accepts an optional folder name and returns the UNSEEN value provided during a SELECT command result. If no folder name is provided, the last folder $imap->select'ed will be used. If a folder name is provided, this will issue a SELECT first.

This method uses caching.

If the server does not provide UNSEEN during SELECT — surprisingly common — this method will fall back and use STATUS to determine the unseen count. 🫶

💡 quick note bestie: this is NOT the opposite of seen below. The UNSEEN value varies from server to server, but per the IMAP spec it should be the number of the first unseen message — if the flag is even provided. (If it's not provided, you're stuck using the SEARCH command to find it. annoying, i know 😭)

See also: search.

current_box

print "Current Mail Box folder: " . $imap->current_box . "\n";

Returns the name of the mail box folder you're currently working in. that's it, that's the whole vibe 🎀

top

my $header = $imap->top( $message_number ); print for @{$header};

Takes a message number as its required parameter, and pulls that message from the currently selected folder. On success you get a list reference holding the header lines. On failure you get nothing back and the errstr() error handler gets set with the error message. 💅

seen

defined( my $seen = $imap->seen( $message_number ) )
    or warn "problem testing for \Seen: "
          . $imap->errstr;

print "msg #$message_number has been \Seen!" if $seen;

A message number is the only thing you gotta pass. It checks the message's \Seen flag: true value back if the message has been seen, a defined false value if the \Seen flag isn't set, and the undefined value if something went wrong while checking the flag status.

⚠️ NOTE: this is not the opposite of unseen up above. This one actually fires off a FETCH command and checks whether the given message has been \Seen before. different beast, same font.

deleted

defined( my $deleted = $imap->deleted( $message_number ) )
    or warn "problem testing for \Deleted: "
          . $imap->errstr;

print "msg #$message_number has been \Deleted!" if $deleted;

Same deal — message number, only required param. It looks at the \Deleted flag: true if the message has been deleted, a defined false value if the \Deleted flag isn't set, and undefined if there was an error checking the flag. 🦋

list

my $message_size  = $imap->list($message_number);
my $mailbox_sizes = $imap->list;

Gives you size info — for one message if you pass the single optional parameter, or for every message in a mailbox if you don't. Single message query = scalar value. Whole mailbox = a hash. On failure nothing comes back and errstr() gets the error message. 📏

fetch

my $headers = $imap->fetch("1:5")

Fetches the headers for messages 1-5 in the current folder. iconic.

for my $midx ( keys %$headers ) {
    for my $hdr in ($headers->{$midx}) {
        say "$hdr"

        # In many situations the headers will be parsed and may not be simple
        # strings (e.g., with the SimpleX RecDescent parse). The simplest
        # way to get a feel for the output is to use a dumper on it.
    }
}

get

my $message = $imap->get( $message_number ) or die $imap->errstr;
my @message_lines = $map->get( $message_number ) or die $imap->errstr;

my $part = $imap->get( $message_number, '1.1' ) or die $imap->errstr;
my @part_lines = $imap->get( $message_number, '1.1' ) or die $imap->errstr;

Fetches a message and returns its lines as an array — or the actual message. On failure you get an empty list and errstr() is set with the error message.

Optionally you can name a part to grab just a specific chunk of a message. That's the raw, encoded body of the part, bestie. The part number is a set of zero or more part specifiers separated by periods, and every message has at least one part. Passing a part of '1' returns the raw, encoded body — only useful if you already know the header info like the encoding. iykyk 🧚

💀 history lesson: get() used to return the array of lines as a reference to the array instead of returning the message or the array itself. It still does that, but heads up — it may get deprecated in the future.

The scalar result is actually a blessed arrayref with the stringify member overloaded. So if you're planning to use that message as a string more than once, forcing the stringification first is lowkey smart:

my $message = $imap->get(1);
   $message = "$message"; # force stringification

That said, it's not normally necessary. don't stress it. ✨

put

$imap->put( $mailbox_name, $message, @flags ) or warn $imap->errstr;

Saves a message to the server under the folder named $mailbox_name. You can optionally pass flags for the mail (like \Seen, \Answered) — but they must start with a slash, fr fr.

If $message is an arrayref, the lines get printed correctly. slay.

put_with_date

$imap->put_with_date( $mailbox_name, $message, $date, @flags ) or warn $imap->errstr;

Same energy as put above — saves a message under the folder named $mailbox_name — but supplying a date sets the IMAP server's internal date for the message, if the server supports it per RFC 3501 Section 6.3.11.

🌸 heads up for Gmail besties: it expects the date format DD-Mon-YYYY hh:mm:ss tz — for example 31-Dec-2016 12:59:59 -0500.

msg_flags

my @flags = $imap->msg_flags( $message_number );
my $flags = $imap->msg_flags( $message_number );

# aught to come out roughly the same
print "Flags on message #$message_number: @flags\n";
print "Flags on message #$message_number: $flags\n";

Catching errors with this one is usually what you want. In scalar context, error detection = testing for defined:

if( defined( my $flags = $imap->msg_flags($num) ) ) {
    # it has $flags!

} else {
    warn "problem listing flags for message #$num: "
       . $imap->errstr;
}

In list context though, you must call waserr() to test for success:

my @flags = $imap->msg_flags($num);
warn "problem listing flags for msg #$num: "
   . $imap->errstr if $imap->waserr;

getfh

my $file = $imap->getfh( $message_number ); print <$file>;

On success you get a file handle pointing at the message identified by the required parameter 🫶. On failure nothing comes back and errstr() gets the error message.

quit

$imap->quit;

OR

$imap->quit(BOOL);

Logs you out of the IMAP server, expunges the selected mailbox, and closes the connection. No error message will ever be returned from this method — it simply does not do that. 💀

Optionally, if BOOL is TRUE (1) then a hard quit happens, which closes the socket connection. That hard quit still issues both the EXPUNGE and LOGOUT commands, but the response is ignored and the socket gets closed right after the commands go out.

logout

$imap->logout;

Just like quit, except it has no hard quit option and it does not expunge the mailbox before hanging up and closing the socket. 🦋

last

my $message_number = $imap->last;

Returns the message number of the last message in the selected mailbox, since the last time that mailbox was selected. On failure nothing comes back and errstr() gets the error message.

delete

print "Gone!" if $imap->delete( $message_number );

Sets the \Deleted flag on the given message (or messages). True on success, false on failure (with errstr() set to the error message). If the flag was already there, no error — it's chill like that. Takes either a message number or a "sequence set" as its only argument.

⚠️ real talk: messages aren't actually deleted until they get expunged (see expunge_mailbox). the flag is just a vibe, not a funeral. 🪦

undelete

print "Resurrected!" if $imap->undelete( $message_number );

Removes the \Deleted flag on the given message. True on success, false on failure with errstr() set. If the flag wasn't there in the first place, no error is produced. it's giving resurrection arc ✨

see

print "You've seen message #$msgno" if $imap->see( $messageno );

Sets the \Seen flag on the given message. True on success, false on failure, and errstr() gets the error message. If the flag was already there, no error. 👑

unsee

print "You've not seen message #$msgno" if $imap->unsee( $messageno );

Removes the \Seen flag on the given message. True on success, false on failure, errstr() gets the error message. If the flag wasn't there, no error is produced. selective memory, we love her 🙈

add_flags

Fun fact: delete and see above are really just calling this function for those flags.

$imap->add_flags( $msgno, qw(\Seen \Deleted) )
    or die $imap->errstr;

sub_flags

And unsee above is really just calling this one for that flag.

$imap->sub_flags( $msgno, '\Seen' ) or die $imap->errstr;

mailboxes

my @boxes   = $imap->mailboxes;
my @folders = $imap->mailboxes("Mail/%");
my @lists   = $imap->mailboxes("lists/perl/*", "/Mail/");

Returns a list of mailboxes. Call it with no arguments and it recurses from the IMAP root to grab every mailbox. The first optional argument is a mailbox path, the second is the path reference. RFC 3501 section 6.3.8 has the full lore if you want it 📚.

On failure nothing comes back and errstr() is set with the error message.

mailboxes_subscribed

my @boxes   = $imap->mailboxes_subscribed;
my @folders = $imap->mailboxes_subscribed("Mail/%");
my @lists   = $imap->mailboxes_subscribed("lists/perl/*", "/Mail/");

Returns a list of mailboxes you're subscribed to 💖. No arguments = recurse from the IMAP root and get everything. First optional argument is a mailbox path, second is the path reference. RFC 3501 has more info.

On failure nothing is returned and the errstr() error handler gets set with the error message. 💅

🎀 create_mailbox

print "Created" if $imap->create_mailbox( "/Mail/lists/perl/advocacy" );

Okay so this one literally creates the mailbox you name in the required argument. That's it, that's the whole vibe. ✨ Returns true on success, false on failure — and when it fails, the errstr() error handler is set with the error message. Bestie, always check your failures. 🫶

💌 expunge_mailbox

my @expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" );
die $imap->errstr if $imap->waserr;

my $expunged = $imap->expunge_mailbox( "/Mail/lists/perl/advocacy" )
    or die $imap->errstr;

This method removes all the mail marked as deleted in the mailbox named in the required argument. Bye felicia 👋🗑️

So what does it return? Either the number of messages that were expunged, or the indexes of those messages — and ngl, that second one has questionable usefulness, because it tends to return numbers that don't actually relate to the message numbers marked with the \Deleted flags. It's giving chaos. 😭

If 0 messages were expunged without error, the function returns 0E0 so it will still test true, but also evaluate to 0. Iconic little Perl trick, fr fr.

⚠️ In list context you must call waserr() to test for success. No cap, don't skip this one.

🌸 delete_mailbox

print "Deleted" if $imap->delete_mailbox( "/Mail/lists/perl/advocacy" );

Deletes the mailbox named in the required argument. Returns true on success, false on failure, and the errstr() error handler is set with the error message. Simple, clean, mildly devastating. 💅

🦋 rename_mailbox

print "Renamed" if $imap->rename_mailbox( $old => $new );

Renames the mailbox in the first required argument to the mailbox named in the second required argument. Returns true on success, false on failure and the errstr() error handler is set with the error message. Two arguments, both required — don't be out here passing one and hoping for the best. 🙈

⭐ folder_subscribe

print "Subscribed" if $imap->folder_subscribe( "/Mail/lists/perl/advocacy" );

Subscribes to the folder. Returns true on success, false on failure and the errstr() error handler is set with the error message. Ring the bell, join the club 🔔

🌈 folder_unsubscribe

print "Unsubscribed" if $imap->folder_unsubscribe( "/Mail/lists/perl/advocacy" );

Un-subscribes to the folder. (Yes, that's the original phrasing — we keep the facts exactly as they are, even when the grammar is lowkey fighting for its life. 😭) Returns true on success, false on failure and the errstr() error handler is set with the error message. It's giving "I'm leaving the group chat" energy. 🚪

🧚 copy

print "copied" if $imap->copy( $message_number, $mailbox );

Copies the message number (or sequence set) in the currently selected mailbox to the folder specified in the second argument. Both arguments are required — yes, both. On success this method returns true. Returns false on failure and the errstr() error handler is set with the error message. 💖

👑 uidcopy

print "copied" if $imap->uidcopy( $message_uid, $mailbox );

This method is identical to copy() above, except that it uses UID numbers instead of sequence numbers. Same energy, different number system. 🔥

⭐ noop

$imap->noop;

Performs a null operation. Sounds like it does nothing (because it kind of does!) but you might actually need it: it can get you updates on a mailbox, or ensure that the server doesn't close the connection as idle. 🫶

RFC 3501 states that servers' idle timeouts must not be less than 30 minutes. So yeah, your connection has at minimum half an hour of chill. 💀

💜 errstr

print "Login ERROR: " . $imap->errstr . "\n" if !$imap->login($user, $pass);

Returns the last error string captured for the last operation which failed. Your receipts, basically. 🧾✨

🩷 waserr

my @flags = $imap->msg_flags(14);
die $imap->errstr if $imap->waserr;

Because msg_flags() can optionally return a list, it's not really possible to detect failure in list context. That's just how it is. 😔 Therefore, you must call waserr() if you wish to detect errors. Periodt.

Few of the Net::IMAP::Simple methods use waserr(). The ones that do will mention it. So if a method's docs name-drop waserr(), that's your cue, bestie. 👀

🍓 list2range

Sometimes you have a long list of sequence numbers which are consecutive and really want to be an IMAP-style range. This is that method. 🎀

my @list  = (5..9, 13..38, 55,56,57);
my $short = $imap->list2range(@list);

# $short how says: 5:9,13:38,55:57

Look at that glow-up. From a whole crowd to three tidy ranges. ✨

🦋 range2list

Pretty much the opposite of list2range. 🔄

my @list = $imap->range2list("1,3,5:9");
# @list is (1,3,5,6,7,8,9);

Ranges in, list out. Math is mathing, we love to see it. 💅

✨ SEARCHING ✨

Okay bestie, so search is the main-character search function: it gives you an array of message numbers when you call it in list context, or the number of matched messages when you call it in scalar context. It takes exactly one argument: the search. 💅

IMAP searching can be a little confusing, and this function makes no attempt to parse your searches. If you wish to do searches by hand, please see <red>RFC 3501</red>. No cap, it's all on you.

IMAP sorting (see <red>RFC 5256</red>) is supported via an optional second argument. The RFC requires the charset be specified, and you can provide that via the optional third argument — it defaults to <mint>UTF-8</mint>. 🦋

Here are a few examples, copied exactly because they are iconic:

my @ids = $imap->search("UNSEEN");
my @ids = $imap->search('SUBJECT "blarg is \"blarg\""');
my @ids = $imap->search('FROM "joe@aol.com"');
my @ids = $imap->search("DELETED");

# example from RFC 3501, search terms are ANDed together
my @ids = $imap->search('FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith"');
# example from RFC 3501, search terms are ORed together
my @ids = $imap->search('OR BODY "blard" SUBJECT "blarg"');

# flagged and ( since x or !from y ):
my @ids = $imap->search('FLAGGED OR SINCE x NOT FROM "y"');
  # no typo above, see the RFC

# example from RFC 5256, sorted by subject and reverse date
my @ids = $imap->search('BODY "zaphod"', 'SUBJECT REVERSE DATE');

Since this module is meant to be simple, <purple>Net::IMAP::Simple</purple> has a few search helpers. If you need fancy booleans and things, you'll have to learn search. If you need a quick search for unseen messages, see below. 🫶

These all return an array of messages or count of messages exactly as the search function does. Some of them take arguments, some do not. They do try to grok your arguments slightly, and the mechanics of this (if any) will be mentioned below. ✨

search_seen 🎀

Returns numbers of messages that have the \Seen flag.

search_recent 🌸

Returns numbers of messages that have the \Recent flag.

search_answered 💖

Returns numbers of messages that have the \Answered flag.

search_deleted 💀

Returns numbers of messages that have the \Deleted flag.

search_flagged 🔥

Returns numbers of messages that have the \Flagged flag.

search_draft 🍓

Returns numbers of messages that have the \Draft flag.

search_unseen 👑

Returns numbers of messages that do not have the \Seen flag.

search_old 🧚

Returns numbers of messages that do not have the \Recent flag.

search_unanswered 🌈

Returns numbers of messages that do not have the \Answered flag.

search_undeleted ⭐

Returns numbers of messages that do not have the \Deleted flag.

search_unflagged 🦋

Returns numbers of messages that do not have the \Flagged flag.

search_smaller 💅

This function takes a single argument we'll call <x> and returns numbers of messages that are smaller than <x> octets. This function will try to force your argument to be a number before passing it to the IMAP server. Literally doing the most. 🫶

search_larger 🎀

This function takes a single argument we'll call <x> and returns numbers of messages that are larger than <x> octets. This function will try to force your argument to be a number before passing it to the IMAP server. Periodt.

search_from 💌

This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the from header. This function will attempt to force your string into the <red>RFC3501</red> quoted-string format.

search_to 💌

This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the to header. This function will attempt to force your string into the <red>RFC3501</red> quoted-string format.

search_cc 💌

This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the cc header. This function will attempt to force your string into the <red>RFC3501</red> quoted-string format.

search_bcc 💌

This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the bcc header. This function will attempt to force your string into the <red>RFC3501</red> quoted-string format.

search_subject 💌

This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the subject header. This function will attempt to force your string into the <red>RFC3501</red> quoted-string format.

search_body 💌

This function takes a single argument we'll call <x> and returns numbers of messages that have <x> in the message body. This function will attempt to force your string into the <red>RFC3501</red> quoted-string format.

search_before ⏰

This function takes a single argument we'll call <x> and returns numbers of messages that were received before <x>. If you have <blue>Date::Manip</blue> installed (optional), this function will attempt to force the date into the format "%d-%b-%Y" (date-monthName-year) as <red>RFC3501</red> requires. If you do not have that module, no attempt will be made to coerce your date into the correct format. 🙈

search_since ⏰

This function takes a single argument we'll call <x> and returns numbers of messages that were received after <x>. If you have <blue>Date::Manip</blue> installed (optional), this function will attempt to force the date into the format "%d-%m-%Y" (date-month-year) as <red>RFC3501</red> requires. If you do not have that module, no attempt will be made to coerce your date into the correct format. 🙈

search_sent_before ⏰

This function takes a single argument we'll call <x> and returns numbers of messages that have a header date before <x>. If you have <blue>Date::Manip</blue> installed (optional), this function will attempt to force the date into the format "%d-%m-%Y" (date-month-year) as <red>RFC3501</red> requires. If you do not have that module, no attempt will be made to coerce your date into the correct format. 🙈

search_sent_since ⏰

This function takes a single argument we'll call <x> and returns numbers of messages that have a header date after <x>. If you have <blue>Date::Manip</blue> installed (optional), this function will attempt to force the date into the format "%d-%m-%Y" (date-month-year) as <red>RFC3501</red> requires. If you do not have that module, no attempt will be made to coerce your date into the correct format. 🙈

🔎 uidsearch

This function works exactly like search() but it returns UIDs instead of sequence numbers. The convenient shortcuts above are not provided for it. That's the whole vibe. 💅

🌈 OTHER NOTES 🌈

🎀 sequence set

Message numbers are never checked before being passed to the IMAP server (this is a "simple" module after all), so in most places where a message number is required, you can instead use so-called sequence sets. Examples, exactly:

$imap->copy(   "3,4,9:22", "ANOTHERBOX" ) or die $imap->errstr;
$imap->delete( "3,4,9:22" ) or die $imap->errstr;

💖 AUTHOR 💖

Creator

Joao Fonseca "<joao_g_fonseca@yahoo.com>"

Maintainer 2004

Casey West "<casey@geeknst.com>"

Maintainer 2005

Colin Faber "<cfaber@fpsn.net>"

Maintainer 2009

Paul Miller "<jettero@cpan.org>"

Copyright (c) 2009-2010 Paul Miller Copyright (c) 2005 Colin Faber Copyright (c) 2004 Casey West Copyright (c) 1999 Joao Fonseca

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.

[This software may have had previous licenses, of which the current maintainer is completely unaware. If this is so, it is possible the above license is incorrect or invalid.]

🐛 BUGS 🐛

There are probably bugs. But don't worry, the current maintainer takes them very seriously and will usually triage (at least) within a single day. 👑

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

👀 SEE ALSO 👀

  • perl
  • Net::IMAP::Server
  • IO::Socket::SSL
  • IO::Socket::INET6

That's the whole page, bestie — it came from perl v5.26.2, dated 2018-05-21, and that's the cute little footer energy we're ending on. 💖✨🎀

📦 where this page comes from