Net::POP3(3pm)

📦
version 5.42.3 · 9 versions
, in alpine 3.24

💖 Net::POP3 💖

okay so bestie, this is Net::POP3 — the Post Office Protocol 3 Client class, straight out of RFC1939. it's giving "let my Perl script talk to a POP3 server" and honestly? iconic. 🎀

✨ SYNOPSIS ✨

use Net::POP3;

# Constructors
$pop = Net::POP3->new('pop3host');
$pop = Net::POP3->new('pop3host', Timeout => 60);
$pop = Net::POP3->new('pop3host', SSL => 1, Timeout => 60);

if ($pop->login($username, $password) > 0) {
  my $msgnums = $pop->list; # hashref of msgnum => size
  foreach my $msgnum (keys %$msgnums) {
    my $msg = $pop->get($msgnum);
    print @$msg;
    $pop->delete($msgnum);
  }
}

$pop->quit;

like, that's the whole vibe right there. 🦋

🌸 DESCRIPTION 🌸

so this module is a client interface to the POP3 protocol, which means your perl5 app gets to talk to POP3 servers. slay. the docs do assume you already know the POP3 protocol from RFC1939, so if you don't, that's your homework bestie 📚.

and here's the fun part: if you've got IO::Socket::SSL installed, it also supports implicit and explicit TLS encryption — so that's POP3S or POP3+STARTTLS. encrypted mail, no cap. 🔥

you gotta make a new Net::POP3 object with the new method first. once that's done, every POP3 command is accessed through method calls on that object. that's it, that's the whole flow.

also, for the record: the Net::POP3 class is a subclass of Net::Cmd and (depending on availability) of IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET. family tree matters, iykyk. 👑

💅 Class Methods 💅

  • new([$host][, %options]) — this is the constructor for a brand new Net::POP3 object. $host is the name of the remote host you want a POP3 connection to. $host is optional, bestie — if you don't pass it, you can pass it as the "Host" option instead (see below). and if you give neither? then the "POP3_Hosts" specified in "Net::Config" get used. someone's gotta pick, and it's not gonna be you. 🙈

%options come in hash-style, key and value pairs. the possible options are:

  • Host — the POP3 host to connect to. it can be a single scalar, exactly as defined for the "PeerAddr" option in IO::Socket::INET, or a reference to an array of hosts to try in turn. the "host" method will return the value that was actually used to connect. 💫
  • Port — the port to connect to. default is 110 for plain POP3 and 995 for POP3s (that's direct SSL, for the uninitiated). 🔌
  • SSL — if the connection should be SSL from the very start, as opposed to upgrading later with "starttls". you can use SSL arguments as documented in IO::Socket::SSL, but honestly it'll usually pick the right arguments for you already. 💅
  • LocalAddr and LocalPort — these get passed directly to IO::Socket so you can bind the socket to a specific local address and port. and for compatibility with older versions, ResvPort can be used instead of LocalPort. vintage. 🎀
  • Domain — passed directly to IO::Socket, and it lets you enforce IPv4 connections even when IO::Socket::IP is the super class. alternatively, Family can be used. 🧚
  • Timeout — maximum time, in seconds, to wait for a response from the POP3 server. default: 120. patience is a virtue but this has limits. ⏳
  • Debug — enable debugging information. for when you need to see everything. 🔍

🫶 Object Methods 🫶

unless stated otherwise, all methods return either a true or false value, where true means the operation was a success. and when a method says it returns a value, failure comes back as undef or an empty list. so like, check your returns bestie. 😭

"Net::POP3" inherits from "Net::Cmd", so the methods defined in "Net::Cmd" can be used to send commands to the remote POP3 server on top of the methods documented here. bonus features, we love that. ✨

  • host() — returns the value used by the constructor, and passed to IO::Socket::INET, to connect to the host. receipts. 🧾
  • auth($username, $password) — attempt SASL authentication.
  • user($user) — send the USER command.
  • pass($pass) — send the PASS command. returns the number of messages in the mailbox. 📬
  • login([$user[, $pass]]) — sends both the USER and PASS commands. if $pass isn't given, "Net::POP3" uses "Net::Netrc" to look up the password using the host and username. and if the username isn't specified either, the current user name gets used. convenient!! 💖

it returns the number of messages in the mailbox. but — and this is the chaotic bit — if there are no messages on the server, the string "0E0" is returned. that gives you a true value in boolean context, but zero in numeric context. yes, really. it's doing both. main character energy. 👑

and if there was an error authenticating the user, undef comes back. 💀

  • starttls(%sslargs) — upgrade an existing plain connection to SSL. you can use SSL arguments as documented in IO::Socket::SSL, but it'll usually use the right arguments already. glow-up moment. 🦋
  • apop([$user[, $pass]]) — authenticate with the server identifying as $user with password $pass. it's similar to "login", but the password is not sent in clear text. privacy queen. 🔐
⚠️ heads up: to use this method you must have the Digest::MD5 or the MD5 module installed — otherwise this method returns undef. no MD5, no APOP, periodt.
  • banner() — return the server's connection banner. hi bestie 👋
  • capa() — returns a reference to a hash of the capabilities of the server. APOP gets added as a pseudo capability. and ngl, the author says they've been unable to find a list of the standard capability values, and some appear to be multi-word while some are not. they make an attempt at intelligently parsing them, but it may not be correct. honesty!! we respect it. 🙈
  • capabilities() — just like capa, but it only uses a cache from the last time we asked the server, so we avoid asking more than once. efficiency slay. ⚡
  • top($msgnum[, $numlines]) — get the header and the first $numlines of the body for message $msgnum. returns a reference to an array containing the lines of text read from the server. 📄
  • list([$msgnum]) — if you call it with an argument, "list" returns the size of the message in octets. if you call it with no arguments, you get a reference to a hash — the keys are the $msgnum's of all undeleted messages and the values are their size in octets. 📊
  • get($msgnum[, $fh]) — get message $msgnum from the remote mailbox. if $fh isn't given, get returns a reference to an array containing the lines of text read from the server. if $fh is given, the lines from the server get printed to the filehandle $fh. your choice, bestie. 🎁
  • getfh($msgnum) — same as get(), but returns a tied filehandle. reading from this filehandle returns the requested message. it'll return EOF at the end of the message and it should not be reused. one and done, no recycling. ♻️
  • last() — returns the highest $msgnum of all the messages accessed. 🏁
  • popstat() — returns a list of two elements: the number of undeleted elements and the size of the mbox in octets. two-for-one. ✌️
  • ping($user) — returns a list of two elements: the number of new messages and the total number of messages for $user. 🏓
  • uidl([$msgnum]) — returns a unique identifier for $msgnum if you give one. if you don't give $msgnum, "uidl" returns a reference to a hash where the keys are the message numbers and the values are the unique identifiers. 🆔
  • delete($msgnum) — mark message $msgnum to be deleted from the remote mailbox. all messages marked to be deleted get removed from the remote mailbox when the server connection is closed. bye boo 👋
  • reset() — reset the status of the remote POP3 server. this includes resetting the status of all messages to not be deleted. undo button, kinda. 🔄
  • quit() — quit and close the connection to the remote POP3 server. any messages marked as deleted will be deleted from the remote mailbox. this is the real goodbye. 🚪
  • can_inet6() — returns whether we can use IPv6.
  • can_ssl() — returns whether we can use SSL. 🔒

🧚 Notes 🧚

💀 okay so this one's important: if a "Net::POP3" object goes out of scope before the "quit" method is called, then the "reset" method will be called before the connection is closed. which means all those messages you marked to be deleted will not be deleted. 😭 the way that will absolutely bite you if you're not paying attention. fr fr.

🎀 EXPORTS 🎀

None. nothing. zero. empty. we gatekeep nothing because there's nothing to gatekeep. ✨

💀 KNOWN BUGS 💀

See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>. go look, it's right there. 🔗

🌈 SEE ALSO 🌈

Net::Netrc, Net::Cmd, IO::Socket::SSL. the whole squad. 🫶

👑 AUTHOR 👑

Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>. legend. 🏆

Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining libnet as of version 1.22_02. passing the torch, we love to see it. 🔥

Copyright (C) 1995-2004 Graham Barr. All rights reserved.

Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved.

🌸 LICENCE 🌸

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e. under the terms of either the GNU General Public License or the Artistic License, as specified in the LICENCE file. free as in bestie. 🕊️

⭐ VERSION ⭐

Version 3.15

🦋 DATE 🦋

20 March 2023

📜 HISTORY 📜

See the Changes file. the lore is all in there. 📖

okay and that's the whole page!! this was Net::POP3(3pm) from the Perl Programmers Reference Guide, perl v5.42.3, dated 2026-11-03 — mwah, go read your mail, ily, bye!! 💅💖🎀🫶

📦 where this page comes from