Net::IMAP(3pm)

📦

version 0.02 · 3 versions

0.02 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.02 · opensuse-leap 16.0
0.02 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, welcome to Net::IMAP(3pm) — from the User Contributed Perl Documentation section. This is Net::IMAP — A client interface to IMAP (Internet Message Access Protocol). 💌

WARNING: This code is in alpha release. Expect the interface to change release to release. 🚨 not me reading alpha and expecting stability — no cap, it will shift.

✨ SYNOPSIS ✨

"use Net::IMAP;"

🦋 DESCRIPTION 🦋

Net::IMAP gives you a perl interface to the client portion of IMAP (Internet Message Access Protocol). It's giving "talk to your mail server from Perl" energy, fr fr.

And ngl the DESCRIPTION literally says: add more meat - describe overall design (commands, responses, callbacks, convenience routines. iconic placeholder energy 💅

👑 METHODS 👑

🌟 new $host, %options

Creates a new Net::IMAP object, connects to $host on port 143, performs some preliminary setup of the session, and returns a reference to the object. slay.

Once connected, it processes the connection banner sent by the server. If the server considers the session to be preauthenticated, new notes the fact, allowing commands to be issued without logging in. main character energy. ✨

The method also issues a capability command, and notes the result. If the server does support IMAP4rev1, the method closes the connection and returns undef. 😭

The client will use non-synchronizing literals if the server supports the LITERAL+ extension (RFC2088) and the NonSyncLits options is set to 1.

The following Net::xAP options are relevant to Net::IMAP:

Synchronous => 1
NonSyncLits => 0
Debug => 0
InternetDraft => 0

Net::IMAP also understands the following options, specific to the module:

EOL => 'lf' — Controls what style of end-of-line processing is presented to the end-programmer. The default, 'lf', assumes that the programmer wants to fling messages terminated with bare LFs when invoking append, and when fetching messages. In this case, the module will map to/from CRLF accordingly.

If EOL is set to 'crlf', the assumption is that the programmer wants messages, or portions of messages, to be terminated with CRLF. It also assumes the programmer is providing messages terminated with the string when invoking the append method, and will not provide an EOL mapping.

🌈 IMAP COMMAND METHODS 🌈

There are numerous commands in the IMAP protocol. Each of these are mapped to a corresponding method in the Net::IMAP module.

Some commands can only be issued in certain protocol states. Some commands alter the state of the session. These facts are indicated in the documentation for the individual command methods.

The following list enumerates the protocol states:

Non-authenticated — The client has not authenticated with the server. Most commands are unavailable in this state. no access bestie
Authenticated — The client has authenticated with the server. we're in
Selected — The client has opened a mailbox on the server. mailbox era

😴 noop

Sends a noop command to the server. It is valid in any protocol state.

This method is useful for placating the auto-logout god, or for triggering pending unsolicited responses from the server. 🙏

✨ capability

The capability method retrieves the capabilities the IMAP server supports. This method is valid in any protocol state.

The server sends a capability response back to the client.

If the response does not indicate support for the LITERAL+ extension, the NonSyncLits option is forced off. forced off, periodt.

🚪 logout

Logs off of the server. This method is valid in any protocol state.

Logs into the server using a simple plaintext password. This method is only valid when the protocol is in the non-authenticated state.

If the server supports RFC2221 (IMAP4 Login Referrals), the completion response could include a referral. See RFC2221 for further information about login referrals.

If successful, the session state is changed to authenticated.

🫶 authenticate $authtype, @authinfo

Logs into the server using the authentication mechanism specified in $authtype. This method is only valid when the protocol is in the non-authenticated state.

The IMAP authenticate command is the same as that documented in RFC2222 (Simple Authentication and Security Layer (SASL)), despite the fact that IMAP predates SASL.

If successful, the session state is changed to authenticated.

The following authentication mechanisms are currently supported:

'login' — This is a variation on the simple login technique, except that the information is transmitted in Base64. This does not provide any additional security, but does allow clients to use authenticate. not it for security, but it works.
'cram-md5' — This implements the authentication mechanism defined in RFC2195 (IMAP/POP AUTHorize Extension for Simple Challenge/Response). It uses keyed MD5 to avoid sending the password over the wire. obsessed with not leaking the password.
'anonymous' — This implements the authentication mechanism defined in RFC2245 (Anonymous SASL Mechanism). Anonymous IMAP access is intended to provide access to public mailboxes or newsgroups. public mailbox vibes.

The method returns undef if $authtype specifies an unsupported mechanism or if the server does not advertise support for the mechanism. The has_authtype method can be used to see whether the server supports a particular authentication mechanism.

In general, if the server supports a mechanism supported by Net::IMAP, the authenticate command should be used instead of the login method.

📬 select $mailbox

Opens the specified mailbox with the intention of performing reading and writing. This method is valid only when the session is in the authenticated or selected states.

If successful, the server sends several responses: flags, exists, resent, as well as ok responses containing a unseen, permanentflags, uidnext, and uidvalidity codes. It also changes the session state to selected.

If server returns a no response containing a newname response code, this means $mailbox does not exist but the server thinks this is because the folder was renamed. In this case, try specifying the new folder name provided with the newname response code. plot twist: it moved.

👀 examine $mailbox

Opens the specified mailbox in read-only mode. This method is valid only when the session is in the authenticated or selected states.

🛠️ create $mailbox [, $partition]

Creates the specified mailbox. This method is valid only when the session is in the authenticated or selected states.

The optional $partition argument is only valid with the Cyrus IMAP daemon. Refer to the section 'Specifying Partitions with "create"' in the "doc/overview" file for that package for further information. This feature can only be used by administrators creating new mailboxes. Other servers will probably reject the command if this argument is used. The results are undefined if another server accepts a second argument. undefined behavior warning, bestie.

🗑️ delete $mailbox

Deletes the specified mailbox. Returns undef if $mailbox is the currently open mailbox. This method is valid only when the session is in the authenticated or selected states.

🏷️ rename $oldmailboxname, $newmailboxname [, $partition]

Renames the mailbox specified in $oldmailbox to the name specified in $newmailbox. This method is valid only when the session is in the authenticated or selected states.

The optional $partition argument is only valid with the Cyrus IMAP daemon. Refer to the section 'Specifying Partitions with "rename"' in the "doc/overview" file for that package for further information. This feature can only be used by administrators. Other servers will probably reject the command if this argument is used. The results are undefined if another server accepts a third argument. again: undefined, no cap.

Subscribe to the specified $mailbox. Subscribing in IMAP is subscribing in Usenet News, except that the server maintains the subscription list. This method is valid only when the session is in the authenticated or selected states.

🔕 unsubscribe $mailbox

Unsubscribe from the specified $mailbox. This method is valid only when the session is in the authenticated or selected states.

📂 list $referencename, $mailbox_pattern

Send an IMAP list command to the server. This method is valid only when the session is in the authenticated or selected states.

Although IMAP folders do not need to be implemented as directories, think of an IMAP reference name as a parameter given to a cd or chdir command, prior to checking for folders matching $mailbox_pattern.

The $mailbox_pattern parameter allows a couple wildcard characters to list subsets of the mailboxes on the server.

* — Matches zero or more characters at the specified location.
% — Like *, matches zero or more characters at the specified location, but does not match hierarchy delimiter characters.

If the last character in $mailbox_pattern is a %, matching levels of hierarchy are also returned. In other words: subfolders.

This method will fail, returning undef, if $mailbox_pattern is *. This behavior is not built into the IMAP protocol; it is wired into Net::IMAP. Doing otherwise could be rude to both the client and server machines. If you want to know why, imagine doing list('#news.', '*') on a machine with a full news feed. The % character should be used to build up a folder tree incrementally. respect the server, bestie.

If successful, the server sends a series of list responses.

Please note that the $referencename is an IMAPism, not a Perl reference. Also note that the wildcards usable in $mailbox_pattern are specific to IMAP. Perl regexps are not usable here. IMAP wildcards only, iykyk.

📑 lsub $referencename, $mailbox_pattern

Sends an IMAP lsub command to the server. The lsub command is similar to the list command, except that the server only returns subscribed mailboxes. This method is valid only when the session is in the authenticated or selected states.

The parameters are the same as those for the list method.

If successful, the server sends a series of lsub responses.

📊 status $mailbox, @statusattrs

Retrieves status information for the specified $mailbox. This method is valid only when the session is in the authenticated or selected states.

Per RFC2060, the @statusattrs can contain any of the following strings:

messages — The number of messages in the mailbox.
recent — The number of messages with the \recent flag set.
uidnext — The UID expected to be assigned to the next mailbox appended to the mailbox. This requires some explanation. Rather than using this value for prefetching the next UID, it should be used to detect whether messages have been added to the mailbox. The value will not change until messages are appended to the mailbox.
uidvalidity — The unique identifier validity value of the mailbox.
unseen — The number of messages without the \seen flag set.

This method will fail, returning undef if $mailbox is the currently open mailbox.

If it works, the server hits you back with one or more status responses. ✨

But okay, real talk: the status operation can be lowkey expensive on some folder implementations, so clients should use this method sparingly. Like. Sparingly sparingly. 💅

append `$mailbox`, `$message` [, `Flags` => `$flaglistref`] [, `Date` => `$date`]

Appends the email message specified in $message to the mailbox specified in $mailbox. This method is valid only when the session is in the authenticated or selected states.

In general, the email message should be a real RFC822 message, although exceptions such as draft messages are reasonable in some situations. Also note that the line terminators in $message need to be CRLF. Yes, for real, CRLF. Do not come to me with your little \n bestie, I'm begging. 😭

The Flags option allows a set of flags to be specified for the message when it is appended. Servers are not required to honor this, but most, if not all, do so.

The Date option forces the internaldate to the specified value. If $date is a string, the format of the string is dd-mmm-yyyy hh:mm:ss [-+]zzzz, where dd is the day of the month (starting from 1), mmm is the three-character abbreviation for the month name, yyyy is the 4-digit year, hh is the hour, mm is the minutes, ss is the seconds, and [-+]zzzz is the numeric timezone offset. This happens to be the same format returned by the internaldate item from the fetch command. If $date is a list reference, it is expected to contain two elements: a time integer and a timezone offset string. The timezone string is expected to be formatted as [-+]zzzz. These two values will be used to synthesize a string in the format expected by the IMAP server. As with the Flags options, servers are not required to honor the Date option, but most, if not all, do so. 🎀

Note that the options are specified at the end of the list of method arguments. This is due to the fact that it is possible to have a $mailbox named Flags or Date. Processing the options at the end of the argument list simplifies argument processing. The order of the arguments will be changed if enough people complain. 🙈

If server returns a no response containing a trycreate response code, this means $mailbox does not exist but the server thinks the command would have succeeded if the an appropriate create command was issued. On the other hand, failure with no trycreate response code generally means that a create should not be attempted.

check

Ask the server to perform a checkpoint of its data. This method is valid only when the session is in the selected state.

While not always needed, this should be called if the client issues a large quantity of updates to a folder in an extended session. Think of it like telling the server "hey bestie, save your work" 💾✨

close

Close the current mailbox. This method is valid only when the session is in the selected state.

If successful, the session state is changed to authenticated.

expunge

Delete messages marked for deletion. This method is valid only when the session is in the selected state.

If successful, the server sends a series of expunge responses.

It will return undef is the mailbox is marked read-only.

💀 expunge is the "are you sure" button that does not ask "are you sure". It's gone bestie. Gone gone.

search [Charset => `$charset`,] `@searchkeys`

Searches the mailbox for messages matching the criteria contained in @searchkeys. This method is valid only when the session is in the selected state.

The @searchkeys list contains strings matching the format described in Section 6.4.4 of RFC2060.

If successful, the server send zero or more search responses. Lack of a search response means the server found no matches. Note that the server can send the results of one search in multiple responses. So don't get it twisted when the hits keep coming in pieces. 🧩

fetch `$msgset`, `'all'|'full'|'fast'|$fetchattr|@fetchattrs`

Retrieves data about a set of messages. This method is valid only when the session is in the selected state.

The $msgset parameter identifies the set of messages from which to retrieve the items of interest. The notation accepted is similar to that found in .newsrc files, except that : is used to specify ranges, instead of -. Thus, to specify messages 1, 2, 3, 5, 7, 8, 9, the following string could be used: '1:3,5,7:9'. The character * can be used to indicate the highest message number in the mailbox. Thus, to specify the last 4 messages in an 8-message mailbox, you can use '5-*'.

The following list enumerates the items that can be retrieved with fetch. Refer to Section 6.4.5 of RFC2060 for a description of each of these items.

body[$section]<$partial>
body.peek[$section]<$partial>

Important: the response item returned for a body.peek is body. 👑 (the server's like "yeah whatever, it's body")

bodystructure
body
envelope
flags
internaldate
rfc822
rfc822.header
rfc822.size
rfc822.text
uid

Please note that the items returning messages, or portion of messages, return strings terminated with CRLF.

RFC2060 also defines several items that are actually macros for other sets of items:

all

A macro equivalent to ('flags', 'internaldate', 'rfc822.size', 'envelope').

full

A macro equivalent to ('flags', 'rfc822.size', 'envelope', 'body').

fast

A macro equivalent to ('flags', 'internaldate', 'rfc822.size').

The all, full, and fast items are not intended to be used with other items. Pick a lane bestie, you can't stack a macro on top of more stuff. 💅

If successful, the server responses with one or more fetch responses.

If the completion response from a fetch command is no, the client should send a noop command, to force any pending expunge responses from the server, and retry the fetch command with $msgset adjusted accordingly. 🫶

store `$msgset`, `$itemname`, `@storeattrflags`

Sets various attributes for the messages identified in $msgset. This method is valid only when the session is in the selected state.

The $msgset parameter is described in the section describing fetch.

The $itemname can be one of the following:

flags

Replaces the current flags with the flags specified in @storeattrflags.

+flags

Adds the flags specified in @storeattrflags to the current flags.

-flags

Removes the flags specified in @storeattrflags from the current flags.

The $itemname can also have .silent appended, which causes the server to not send back update responses for the messages. 🤫

If successful, and .silent is used used in $itemname, the server response with a series of fetch responses reflecting the updates to the specified messages.

If the completion response from a store command is no, the client should send a noop command, to force any pending expunge responses from the server, and retry the store command with $msgset adjusted accordingly.

The @storeattrflags is a list of flag strings.

copy `$msgset`, `$mailbox`

Copy the messages $msgset to the specified mailbox. This method is valid only when the session is in the selected state.

The $msgset parameter is described in the section describing fetch.

uid_copy `$msgset`, `$mailbox`

A variant of copy that uses UIDs in $msgset, instead of message numbers. This method is valid only when the session is in the selected state.

uid_fetch `$msgset`, `'all'|'full'|'fast'|$fetchattr|@fetchattrs`

A variant of fetch that uses UIDs, instead of message numbers, in $msgset and fetch responses. This method is valid only when the session is in the selected state.

uid_search [Charset => `$charset`,] `@searchkeys`

A variant of search that uses UIDs, instead of message numbers, in $msgset and search responses. This method is valid only when the session is in the selected state.

uid_store `$msgset`, `$itemname`, `@storeattrflags`

A variant of store that uses UIDs, instead of message numbers, in $msgset and fetch responses. This method is valid only when the session is in the selected state.

💖 CONVENIENCE ROUTINES 💖

In addition to the core protocol methods, Net::IMAP provides several methods for accessing various pieces of information. It's giving quality of life. ✨

is_preauth

Returns a boolean valud indicating whether the IMAP session is preauthenticated.

Returns the banner string issued by the server at connect time. 🎀

capabilities

Returns the list of capabilities supported by the server, minus the authentication capabilities. The list is not guaranteed to be in any specific order. So like, don't assume, bestie.

has_capability `$capname`

Returns a boolean value indicating whether the server supports the specified capability.

authtypes

Returns a list of authentication types supported by the server.

has_authtype `$authname`

Returns a boolean value indicating whether the server supports the specified authentication type.

qty_messages

Returns the quantity of messages in the currently selected folder.

qty_recent

Returns the quantity of recent messages in the currently selected folder.

first_unseen

Returns the message number of the first unseen messages in the currently selected folder.

uidvalidity

Returns the uidvalidity value for the currently selected folder. This is useful for IMAP clients that cache data in persistent storage. Cache data for a mailbox should only be considered valid if the uidvalidity is the same for both cached data and the remote mailbox. See Section 2.3.1.1 of RFC2060 for further details.

🫶 If uidvalidity changed, your cache is cooked. Throw it out. Do not pass go.

uidnext

Returns the uidnext value for the currently selected folder.

permanentflags

Returns the list of permanent flags the server has identified for the currently open mailbox.

If a \* flag is present, the server allows new persistent keywords to be created. 👑

is_permanentflag `$flag`

Returns a boolean value indicating whether the server considers $flag to be a permanent flag.

flags

Returns a list of the flags associated with the mailbox.

has_flag `$flag`

Returns a boolean value indicating whether the given $flag is defined for the mailbox.

mailbox

Returns the name of the currently open mailbox. Returns undef if no mailbox is currently open. 🕳️

is_readonly

Returns a boolean value indicating whether the currently open mailbox is read-only.

🌈 NAMESPACE EXTENSION 🌈

The following methods are available if the server advertises support for RFC2342 (IMAP4 Namespace). Refer to that RFC for additional information.

namespace

Sends a namespace command to the server, if the server advertises support for the extension extension.

💅 ACCESS CONTROL EXTENSION 💅

okay so these next methods are only there for you if the server is out here advertising support for RFC2086 (that's the IMAP4 ACL Extension, bestie). Go read that RFC for the extra lore, but here's the rundown 🎀

`setacl $mailbox, $identifier, $modrights`

Sets the access control list for $identifier on $mailbox, according to the rights chilling inside $modrights. Slay.

$identifier is usually an account name, but it can also point at abstract entities — like groups, iykyk.

The format for $modrights is documented in RFC2086, so go check that out before you start typing.

`getacl $mailbox`

Retrieves the access control list for $mailbox. Giving "show me the receipts" energy ✨

`deleteacl $mailbox, $identifier`

Deletes all access control list entries for $identifier from $mailbox. Gone. Blocked. Periodt 💅

`listrights $mailbox, $identifier`

Lists the rights available to $identifier for $mailbox.

`myrights $mailbox`

Lists the rights the current user has for $mailbox. Main character check 🪞

🌸 QUOTA EXTENSION 🌸

These methods show up when the server advertises support for RFC2087 (the IMAP4 Quota Extension). RFC has the full tea, but here's the vibe ☕

`getquota $quotaroot`

Lists the resource usage and limits for $quotaroot.

`setquota $quotaroot, @setquotalist`

Sets the resource limits for $quotaroot to @setquotalist.

Heads up bestie: the valid values for @setquotalist are server-dependant. So like, ask your server, not me 🫶

`getquotaroot $mailbox`

Lists the quota roots for $mailbox.

🦋 UIDPLUS EXTENSION 🦋

Just the one method here, and it's available when the server advertises support for RFC2359 (the IMAP4 UIDPLUS Extension). RFC for the deep dive, always 📖

`uid_expunge $msgset`

A variant of expunge that lets the operation be narrowed down to only the messages with UIDs specified in $msgset. So like, expunge but with taste 💅

The $msgset parameter is described in the section describing fetch.

🎀 CALLBACKS 🎀

So here's the whole situation: lots of the command methods make the server send back response data. Net::IMAP handles each response by parsing the data, packaging it up in an appropriate object, and then optionally calling a programmer-defined callback for that response. This callback mechanism is literally how programmers get their hands on the data retrieved from the server. No callback, no data, no cap 🔥

`set_untagged_callback $item, $coderef`

Assigns a programmer-defined code reference to the associated untagged response. When an untagged response matching $item comes in, $coderef gets called, with the IMAP object and the associated response object passed as parameters. Two args, both iconic 👑

The default callback for the ok, bye, bad, and no untagged responses includes code to output the text from alert responses to stderr, using carp. So if you go and set your own callback for these responses, be sure to handle alert codes. Per Section 7.1 of RFC2060, clients are required to clearly display alert messages to users. Not optional. Don't skip it 🙈

🌈 RESPONSE OBJECTS 🌈

Like we said in the last section, responses get parsed and packaged into response objects, and then those get passed to callbacks. Every type of response has its own corresponding object class. This section is the tour of all the response objects on offer, bestie 🫶

All the class names itemized below are prefixed with Net::IMAP. So like, Net::IMAP::Response, that whole vibe.

General rules, get these memorized ✨

IMAP nil items are set to undef in the parsed data.
IMAP parenthetical lists get converted to list references (of one form or another).
Atoms, quoted strings, and literals are presented as Perl strings.

Also: the condition responses (ok, no, bad, bye, and preauth) can include a response code. Section 7.1 in RFC2060 has a description of each of the standard response codes. Go look 👀

Response

This is the object class for completion responses. The finale, the closing credits 🎬

`is_tagged`

Returns a boolean value indicating whether the response is tagged. In the case of tagged completion responses, this value is always 1. Always. Every time 💯

`has_trycreate`

Returns a boolean value indicating whether the TRYCREATE response code is present in the response. You can use this after a failed append or copy command to figure out whether the server thinks the operation would succeed if a create was issued for the associated mailbox. Super useful, lowkey 🧠

UntaggedResponse

This class is common to all untagged server responses.

`tag`

Returns a string containing the tag associated with the response. For untagged responses, this is always *. Yep, always that lil star ⭐

`is_tagged`

Returns a boolean value indicating whether the response is tagged. Obviously, for untagged responses, this value is always 0.

`parent`

Returns a reference to the parent IMAP object. Found family 🫶

Ok

This is a container for untagged ok responses from the server. Good news only 💚

`code`

Returns a list reference containing response code elements in the response. Returns undef if no response code is present.

`name`

Returns the name of the response. In the case of Ok, this returns 'ok'. This method exists as a convenience for end-programmers who wanna write one common subroutine for one or more of the responses Ok, No, Bad, and Bye. DRY queen ✨

No

This is a container for untagged no responses from the server. 🚫

Bad

This is a container for untagged bad responses from the server. 💀

Bye

This is a container for untagged bye responses from the server. 👋

Expunge

This is a container for expunge responses from the server.

The information returned by qty_messages is automatically updated when expunge responses are received. Auto-update, no manual labour 💅

`msgnum`

Returns the message number specified in the expunge response.

Capability

This is a container for capability responses.

`capabilities`

Returns the list of capabilities supported by the server, minus the authentication capabilities. The list is not guaranteed to be in any specific order, so don't come for me about the ordering 🙈

`has_capability $capname`

Returns a boolean value indicating whether the server supports the specified capability.

`authtypes`

Returns a list of authentication types supported by the server.

`has_authtype $authname`

Returns a boolean value indicating whether the server supports the specified authentication type.

List

This is a container for list responses.

`mailbox`

Returns the name of the mailbox contained in the object.

`delimiter`

Returns the hierarchy delimiter associated with the mailbox.

`flags`

Returns a list of the flags associated with the mailbox.

`has_flag $flag`

Returns a boolean value indicating whether the given $flag is defined for the mailbox.

List

This one is a container for lsub responses. It provides the same interface as the Net::IMAP::List class. Same energy, different letter 💫

Fetch

This is a container for fetch responses.

Responses for partial fetches bear special mention, and I mean that fr fr. While both the starting byte and the quantity of bytes are specified when you do partial fetches with the fetch command, the corresponding response will only show the starting byte. In other words, the command

$imap->fetch(1, 'body[]<0.1024>'

will, if successful, result in a fetch response item of body[]<0> containing a 1024 octet value. So to match a given response for a partial fetch, you might need to use length to match it up with the corresponding item you specified in the fetch command. Sneaky, but that's just how it is 🫠

`msgnum`

Returns the message number identified in the response.

`items`

Returns the list of data item names contained in the response. Again, the list is not guaranteed to be in any specific order.

`item $item`

Returns the data associated with the specified data item.

The following list enumerates the data types associated with each fetch item:

envelope — Net::IMAP::Envelope
bodystructure — Net::IMAP::BodyStructure
body — Net::IMAP::BodyStructure
flags — Net::IMAP::Flags
UID — Integer
rfc822.size — Integer
default — String

Status

This is a container for status responses.

`mailbox`

Returns a string containing the mailbox the status information is associated with.

`items`

Returns the list of status items contains in the status response.

`item $item`

Returns the value of the $item status item.

Search

This is a container for search responses. 🔍

`msgnums`

Returns the list of message numbers contained in the response.

Flags

This is a container for flags responses. 🚩

`flags`

Returns the list of flags contained in the response.

`has_flag $flag`

Returns a boolean value indicating whether the specified flag is contained in the response.

Bonus: as a convenience, the information from the flags response is also stored in the parent Net::IMAP object, and is available via Net::IMAP versions of the flags and has_flags methods. Two places at once, multitalented 💅

Exists

This is a container for exists responses.

`exists`

Returns the quantity of messages in the currently selected mailbox.

This information is also available in the qty_messages method in the Net::IMAP class. Same data, different doorway 🚪

Recent

This is a container for recent responses.

`recent`

Returns the number of messages with the \recent flag set.

This information is also available in the qty_recent method in the Net::IMAP class.

Namespace

This is a container for namespace responses.

`personal [$namespace]`

With no argument specified, returns a list of personal namespaces. If $namespace is specified, returns the delimiter character for that specific personal namespace.

`other_users [$namespace]`

With no argument specified, returns a list of other users' namespaces. If $namespace is specified, returns the delimiter character for that specific other users' namespace.

`shared [$namespace]`

With no argument specified, returns a list of shared namespaces. If $namespace is specified, returns the delimiter character for that specific shared namespace.

ACL

This is a container for acl responses.

`mailbox`

Returns the name of the mailbox associated with the given ACL data.

`identifiers`

Returns a list of identifiers contained in the ACL data.

`identifier $identifier`

Listrights

This is a container for listrights responses.

`mailbox`

Returns the name of the mailbox associated with the given rights.

`identifier`

Returns a string containing the identifier associated with the rights.

`rights`

Returns a string containing the rights contained in the response.

Myrights

This is a container for myrights responses.

`mailbox`

Returns the name of the mailbox associated with the given rights.

`rights`

Returns a string containing the rights contained in the response.

Quota

This is a container for quota responses.

`quotaroot`

Returns a string containing the name of the quota root in the response.

`quotas`

Returns a list of the quotas contained in the response.

`usage $quota`

Returns the usage value associated with the given $quota. Returns undef if the given $quota is not present in the response. No quota, no answer 🙈

`limit $quota`

Returns the usage limit associated with the given $quota. Returns undef if the given $quota is not present in the response.

💖 Quotaroot 💖

Okay so this one is a lil container for "quotaroot" responses. It's giving storage vibes. 🎀

`mailbox`

Returns the name of the mailbox that's associated with the quotaroot data. Like, the mailbox it belongs to. 💌

`quotaroots`

If you call it in an array context, it returns the list of quotaroots associated with the mailbox. If you call it in a scalar context, it returns a list reference. Periodt. ✨

🌈 MISC FETCH OBJECTS 🌈

A "fetch" response can be relatively complicated. No cap. This section documents various classes and methods associated with the various pieces of information available in "fetch" responses. It's a whole vibe. 🦋

🧚 BodyStructure 🧚

This is a container for "bodystructure" items in "fetch" responses.

`type`

Returns a string containing the MIME type of the message. This is the left-hand portion of a MIME media type. For example, the type of "text/plain" is "text". Slay. 💅

`subtype`

Returns a string containing the MIME subtype of the message. This is the right-hand portion of a MIME media type. For example, the subtype of "text/plain" is "plain". Iconic. ✨

`parameters`

Returns a reference to a hash containing the key/value attribute pairs in the "Content-Type" field.

If, for example, the "Content-Type" field was:

Content-Type: text/plain; charset=us-ascii

The hash would contain one entry with a key of "charset", and a value of "us-ascii". The key is always forced to be lowercase, but the case of the value is retained from the server. Lowkey important. 💖

`disposition`

Returns the disposition type in the "Content-Disposition" field. Returns "undef" if no such field exists. Not me checking for undef. 😭

`disp_parameters`

Returns a reference to a hash containing the key/value attribute pairs in the "Content-Disposition" field. A reference to an empty hash is returned if no such field exists, or if there are no parameters in the field. So if it's empty, you get an empty hash ref. 🫶

`language`

Returns a reference to a list of the language tags present in the "Content-Language" field. Returns a reference to an empty hash if no such field is present. (Yes, it says hash even though it's a list — we don't make the rules, bestie.) 💀

🌸 Multipart 🌸

This is a container for "BodyStructure" objects that are multipart entities. It's giving nested energy. 🎀

`parts`

Returns a list reference of the body parts contained in the multipart entity. All the lil pieces. 🧩

🦋 Bodypart 🦋

This is a container for singlepart entities in "BodyStructure" and "Multipart" objects.

`id`

Return a string containing the contents of the "Content-ID" field, if one is present, otherwise returns undef. No ID? Undef. 💅

`description`

Return a string containing the contents of the "Content-Description" field, if one is present, otherwise returns undef. Same vibe. ✨

`encoding`

Returns a string containing the contents of the "Content-Transfer-Encoding" field. Returns "undef" if no such field is in the entity. 👑

`size`

Returns the number of octets in the entity. Octets, not vibes. 🔥

`lines`

If the MIME content type is "message/rfc822" or the major type is "text", returns the number of lines in the entity, else returns "undef". Conditional queen. 💖

`envelope`

If the MIME content type is "message/rfc822", returns a "Net::IMAP::Envelope" object, otherwise returns undef. 🫶

`bodystructure`

If the MIME content type is "message/rfc822", returns a "Net::IMAP::BodyStructure" object, otherwise returns undef. Recursive realness. 🌀

`md5`

Returns a string containing the contents of the "Content-MD5" field. Returns "undef" if no such field is in the entity. Secure-ish. 🔐

💌 Envelope 💌

This is a container for envelope data in "fetch" responses.

For those familiar with SMTP, this is not the same type envelope. Rather, it is a composite structure containing key source, destination, and reference information in the message. When retrieved from the server, it is populated into a "Net::IMAP::Envelope" object. The following methods are available. Main character energy fr fr. 👑

`date`

Returns a string with the contents of the "Date" field. 📅

`subject`

Returns a string with the contents of the "Subject" field. The tea. ☕

`from`

Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "From" field. 💌

`sender`

Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Sender" field. If no "Sender" field is present in the message, the server will default it to the contents of the "From" field. Default behavior, slay. ✨

`reply_to`

Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Reply-To" field. If no "Reply-To" field is present in the message, the server will default it to the contents of the "From" field. Same default energy. 💅

`to`

Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "To" field. Will return "undef" if no "To" field exists in the message. No To? Undef. 😭

`cc`

Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Cc" field. Will return "undef" if no "Cc" field exists in the message. 👯

`bcc`

Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Bcc" field. Will return "undef" if no "Bcc" field exists in the message. Secret copy vibes. 🤫

`in_reply_to`

Returns a string with the contents of the "In-Reply-To" field. Returns "undef" if no such field is present in the message. 🔁

`message_id`

Returns a string with the contents of the "Date" field. Returns "undef" if no such field is present in the message. (Yes, it says "Date" here too — we're just the messenger, bestie.) 💀

🎀 Addr 🎀

This is a container for address structures in "Envelope" objects.

`phrase`

Returns a string containing the phrase portion of the address, or "undef" if no phrase is present. 💬

`route`

Returns a string containing the route portion of the address, or "undef" if no route information is present. 🛣️

`localpart`

Returns a string containing the localpart portion of the address, or "undef" if no localpart is present. 📍

`domain`

Returns a string containing the domain portion of the address, or "undef" if no domain is present. 🌐

`as_string`

Returns a string representation of the contents of the object. Stringified realness. ✨

🫣 CAVEATS 🫣

Minimal testing has been done against the various IMAP server implementations. Refer to "BUGS" for known bugs/malfeatures. So like, be aware. Not everything is slay. 😬

👑 AUTHOR 👑

Kevin Johnson <kjj@pobox.com>

📜 COPYRIGHT 📜

And that's the whole vibe, bestie. This page came from Perl v5.36.0, dated 2022-11-19, and it's Net::IMAP(3pm). Go forth and fetch responsibly. 💖✨🦋

📦 where this page comes from

debian bookworm: libnet-imap-perl 0.02-12 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libnet-imap-perl 0.02-12 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libnet-imap-perl 0.02-12 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libnet-imap-perl 0.02-12 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libnet-imap-perl 0.02-12 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Net::IMAP(3pm)

💖 NAME 💖

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

👑 METHODS 👑

🌟 new $host, %options

🌈 IMAP COMMAND METHODS 🌈

😴 noop

✨ capability

🚪 logout

🔐 login $user, $password

🫶 authenticate $authtype, @authinfo

📬 select $mailbox

👀 examine $mailbox

🛠️ create $mailbox [, $partition]

🗑️ delete $mailbox

🏷️ rename $oldmailboxname, $newmailboxname [, $partition]

🔔 subscribe $mailbox

🔕 unsubscribe $mailbox

📂 list $referencename, $mailbox_pattern

📑 lsub $referencename, $mailbox_pattern

📊 status $mailbox, @statusattrs

append $mailbox, $message [, Flags => $flaglistref] [, Date => $date]

check

close

expunge

search [Charset => $charset,] @searchkeys

fetch $msgset, 'all'|'full'|'fast'|$fetchattr|@fetchattrs

store $msgset, $itemname, @storeattrflags

copy $msgset, $mailbox

uid_copy $msgset, $mailbox

uid_fetch $msgset, 'all'|'full'|'fast'|$fetchattr|@fetchattrs

uid_search [Charset => $charset,] @searchkeys

uid_store $msgset, $itemname, @storeattrflags

💖 CONVENIENCE ROUTINES 💖

is_preauth

banner

capabilities

has_capability $capname

authtypes

has_authtype $authname

qty_messages

qty_recent

first_unseen

uidvalidity

uidnext

permanentflags

is_permanentflag $flag

flags

has_flag $flag

mailbox

is_readonly

🌈 NAMESPACE EXTENSION 🌈

namespace

💅 ACCESS CONTROL EXTENSION 💅

setacl $mailbox, $identifier, $modrights

getacl $mailbox

deleteacl $mailbox, $identifier

listrights $mailbox, $identifier

myrights $mailbox

🌸 QUOTA EXTENSION 🌸

getquota $quotaroot

setquota $quotaroot, @setquotalist

getquotaroot $mailbox

🦋 UIDPLUS EXTENSION 🦋

uid_expunge $msgset

🎀 CALLBACKS 🎀

set_untagged_callback $item, $coderef

🌈 RESPONSE OBJECTS 🌈

Response

is_tagged

has_trycreate

UntaggedResponse

tag

is_tagged

parent

Ok

code

name

No

append `$mailbox`, `$message` [, `Flags` => `$flaglistref`] [, `Date` => `$date`]

search [Charset => `$charset`,] `@searchkeys`

fetch `$msgset`, `'all'|'full'|'fast'|$fetchattr|@fetchattrs`

store `$msgset`, `$itemname`, `@storeattrflags`

copy `$msgset`, `$mailbox`

uid_copy `$msgset`, `$mailbox`

uid_fetch `$msgset`, `'all'|'full'|'fast'|$fetchattr|@fetchattrs`

uid_search [Charset => `$charset`,] `@searchkeys`

uid_store `$msgset`, `$itemname`, `@storeattrflags`

has_capability `$capname`

has_authtype `$authname`

is_permanentflag `$flag`

has_flag `$flag`

`setacl $mailbox, $identifier, $modrights`

`getacl $mailbox`

`deleteacl $mailbox, $identifier`

`listrights $mailbox, $identifier`

`myrights $mailbox`

`getquota $quotaroot`

`setquota $quotaroot, @setquotalist`

`getquotaroot $mailbox`

`uid_expunge $msgset`

`set_untagged_callback $item, $coderef`

`is_tagged`

`has_trycreate`

`tag`

`is_tagged`

`parent`

`code`

`name`

`msgnum`

`capabilities`

`has_capability $capname`

`authtypes`

`has_authtype $authname`

`mailbox`

`delimiter`

`flags`

`has_flag $flag`

`msgnum`

`items`

`item $item`

`mailbox`

`items`

`item $item`

`msgnums`

`flags`

`has_flag $flag`

`exists`

`recent`

`personal [$namespace]`

`other_users [$namespace]`

`shared [$namespace]`

`mailbox`

`identifiers`

`identifier $identifier`

`mailbox`

`identifier`

`rights`

`mailbox`

`rights`

`quotaroot`

`quotas`

`usage $quota`

`limit $quota`

`mailbox`

`quotaroots`

`type`

`subtype`

`parameters`

`disposition`

`disp_parameters`

`language`

`parts`

`id`

`description`

`encoding`

`size`