Mail::POP3Client(3pm)

📦
version 2.21 · 5 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Mail::POP3Client(3pm) 💖

okay bestie, sit DOWN, because this is Mail::POP3Client(3pm) — the Perl 5 module from the User Contributed Perl Documentation that lets you talk to a POP3 server, and honestly? she's iconic.

✨ NAME ✨

Mail::POP3Client — a Perl 5 module to talk to a POP3 (RFC1939) server. that's it, that's the name, she's simple and she knows it 💅

🌸 SYNOPSIS 🌸

okay so here's the vibe, a bunch of ways to get in:

  use Mail::POP3Client;
  $pop = new Mail::POP3Client( USER     => "me",
                               PASSWORD => "mypassword",
                               HOST     => "pop3.do.main" );
  for( $i = 1; $i <= $pop->Count(); $i++ ) {
    foreach( $pop->Head( $i ) ) {
      /^(From|Subject):\s+/i && print $_, "\n";
    }
  }
  $pop->Close();

  # OR with SSL
  $pop = new Mail::POP3Client( USER     => "me",
                               PASSWORD => "mypassword",
                               HOST     => "pop3.do.main",
                               USESSL   => true,
                             );

  # OR
  $pop2 = new Mail::POP3Client( HOST  => "pop3.otherdo.main" );
  $pop2->User( "somebody" );
  $pop2->Pass( "doublesecret" );
  $pop2->Connect() >= 0 || die $pop2->Message();
  $pop2->Close();

  # OR to use your own SSL socket...
  my $socket = IO::Socket::SSL->new( PeerAddr => 'pop.securedo.main',
                                     PeerPort => 993,
                                     Proto    => 'tcp') || die "No socket!";
  my $pop = Mail::POP3Client->new();
  $pop->User('somebody');
  $pop->Pass('doublesecret');
  $pop->Socket($socket);
  $pop->Connect();

like, pick your fighter 🫶 the last one is for when you're feeling main character and you want to bring your own SSL socket.

🦋 DESCRIPTION 🦋

this module is an Object-Oriented interface to a POP3 server. periodt. she implements RFC1939 — and yeah, the receipts are right here: http://www.faqs.org/rfcs/rfc1939.html

🎀 EXAMPLES 🎀

here's a lil baby example that lists out the From: and Subject: headers sitting in your remote mailbox, no cap:

  #!/usr/local/bin/perl

  use Mail::POP3Client;

  $pop = new Mail::POP3Client( USER     => "me",
                               PASSWORD => "mypassword",
                               HOST     => "pop3.do.main" );
  for ($i = 1; $i <= $pop->Count(); $i++) {
    foreach ( $pop->Head( $i ) ) {
      /^(From|Subject):\s+/i and print $_, "\n";
    }
    print "\n";
  }

look at her go 🧚 so clean, so demure.

👑 CONSTRUCTORS 👑

the old style (deprecated, we don't gatekeep but we do side-eye 👀)

   new Mail::POP3Client( USER, PASSWORD [, HOST, PORT, DEBUG, AUTH_MODE]
);
lowkey deprecated, bestie. still works, but the new style is the moment.

the new style (shown with defaults, so you know exactly what you're getting) ✨

   new Mail::POP3Client( USER      => "",
                         PASSWORD  => "",
                         HOST      => "pop3",
                         PORT      => 110,
                         AUTH_MODE => 'BEST',
                         DEBUG     => 0,
                         TIMEOUT   => 60,
                         LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]',
                         SOCKET => undef,
                         USESSL => 0,
                       );

and now the tea on every single one of those:

  • USER — this is the userID of the account on the POP server
  • PASSWORD — the cleartext password for that userID (yes, cleartext, that's just what it is 🙈)
  • HOST — the POP server name or IP address, and the default is 'pop3'
  • PORT — the POP server port, default is 110
  • DEBUG — literally any non-null, non-zero value turns debugging on; default is 0
  • AUTH_MODE — pass 'APOP' to force APOP (MD5) authorization. default is 'BEST'
  • TIMEOUT — sets a timeout value for socket operations, default is 60
  • LOCALADDR — lets you select a local inet address to use

and that's the whole squad for constructors 💖 more is coming, don't go anywhere —

🌸 METHODS 🌸

These commands exist to make writing a POP3 client way easier, bestie. They do <em>not</em> necessarily map directly to the POP3 commands defined in RFC1081 or RFC1939, even though all commands should be supported. And heads up: some of these return multiple lines as an array when you call them in an array context. ✨

  • Head( MESSAGE_NUMBER [, PREVIEW_LINES ] ) — grabs the headers of the message you point at, and it gives you back an array or a string depending on context, obviously. You can also pass a number of preview lines and those get returned right along with the headers. Warning though: not every POP3 server implementation supports the preview-lines thing, because it's marked as optional in the RFC. Submitted by Dennis Moroney <dennis@hub.iwl.net>. 🫶
  • Body( MESSAGE_NUMBER ) — the body of the message you specify. Array of lines or a string, depending on context. That's it, that's the whole thing. 💅
  • BodyToFile( FILE_HANDLE, MESSAGE_NUMBER ) — takes the body of the message and writes it straight into the file handle you hand over. Like so:
my $fh = new IO::Handle(); $fh->fdopen( fileno( STDOUT ), "w" ); $pop->BodyToFile( $fh, 1 );

Does no stripping of NL or CR. None. Zero. It gives you exactly what it got. 😭

  • HeadAndBody( MESSAGE_NUMBER ) — head <em>and</em> body of the message, as an array of lines or a string depending on context. The moment you've been waiting for. 👑

Example:

foreach ( $pop->HeadAndBody( 1 ) )
   print $_, "\n";

That prints out the complete text of message 1. Ate. 🔥

  • HeadAndBodyToFile( FILE_HANDLE, MESSAGE_NUMBER ) — head and body, written to your file handle:
my $fh = new IO::Handle(); $fh->fdopen( fileno( STDOUT ), "w" ); $pop->HeadAndBodyToFile( $fh, 1 );

And again: does no stripping of NL or CR.

  • Retrieve( MESSAGE_NUMBER ) — literally the same as HeadAndBody.
  • RetrieveToFile( FILE_HANDLE, MESSAGE_NUMBER ) — literally the same as HeadAndBodyToFile.
  • Delete( MESSAGE_NUMBER ) — marks the message number as DELETED. It only actually becomes effective on QUIT (which is what invoking the Close method does), so don't be out here thinking it's gone-gone. You can undo it with a Reset message. ✨
  • Connect — starts the connection to the POP3 server. You can pass in the host and the port. Returns 1 if the connection succeeds, or 0 if it fails (and in that case Message will hold a reason for you). Note the drama: the constructor <em>always</em> returns a blessed reference to a Mail::POP3Client object. That may change in a 3.x release, but never in a 2.x release. No cap.
  • Close — closes the connection gracefully. POP3 says this will perform any pending deletes on the server. So yeah, that's the moment the deletes land. 🫣
  • Alive — returns true or false on whether the connection is active.
  • Socket — returns the file descriptor for the socket, or sets it if you supply one.
  • Size — set/return the size of the remote mailbox. It gets set by POPStat.
  • Count — set/return the number of remote messages. It gets set during Login.
  • Message — the last status message received from the server, or a message describing whatever problem got encountered. Your lil diagnostic bestie. 💜
  • State — the internal state of the connection: DEAD, AUTHORIZATION, TRANSACTION. Vibe check, but for your socket.
  • POPStat — returns the results of a POP3 STAT command. Sets the size of the mailbox while it's at it.
  • List([message_number]) — called with an argument, it returns the size of that message number, in exactly this format:
<message_number> <size_in_bytes>

If message_number is omitted, List behaves the same as ListArray, returning an indexed array of the sizes of each message in that same format.

You can parse the size in bytes using split:

 ($msgnum, $size) = split('\s+', $pop -> List( n ));
  • ListArray — returns a list of the sizes of each message. It's an indexed array, where each message number is an index (starting from 1) and the value is the next entry on the line. ⚠️ Beware: some servers send additional info for each message on the list command, and that info may be lost. It's giving data loss, unfortunately. 💀
  • Uidl( [MESSAGE_NUMBER] ) — returns the unique ID for the given message (or all of them, if you don't give one). You get an indexed array with an entry for each valid message number, and indexing begins at 1 to coincide with the server's own indexing. Matching energy. 🌈
  • Capa — queries the server capabilities, as described in RFC 2449. Returns the capabilities in an array. Valid in all states. ✨
  • XTND — optional extended commands. Transaction state only, bestie.
  • UTF8 — adds support for UTF8.
  • Last — returns the number of the last message, retrieved from the server.
  • Reset — tells the server to unmark any message marked for deletion. The undoing of the doing. 🙈
  • User( [USER_NAME] ) — set/return the current user name.
  • Pass( [PASSWORD] ) — set/return the current user name. Yeah. That is genuinely what the page says, even though the argument is PASSWORD. We report, we do not judge. 💅
  • Login — attempts to login to the server connection.
  • Host( [HOSTNAME] ) — set/return the current host.
  • Port( [PORT_NUMBER] ) — set/return the current port number.

🦋 IMAP COMPATIBILITY 🦋

Basic Mail::IMAPClient method calls are also supported: close, connect, login, message_string, Password, and unseen.

Also, empty stubs are provided for Folder, folders, Peek, select, and Uid. They're there, they're just vibes. 🫶

🎀 REQUIREMENTS 🎀

This module does not have mandatory requirements for modules that are not part of the standard Perl distribution.

However — plot twist — APOP needs Digest::MD5, and CRAM-MD5 needs Digest::HMAC_MD5 and MIME::Base64. So if you're rolling with those auth modes, go get your dependencies sorted first. ✨

👑 AUTHOR 👑

Sean Dowd <pop3client@dowds.net>

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

🌟 CREDITS 🌟

Based loosely on News::NNTPClient by Rodger Anderson <rodger@boi.hp.com>. Shoutout to the ancestor. 🫡

🌈 SEE ALSO 🌈

  • perl(1)
  • the Digest::MD5 manpage, the Digest::HMAC_MD5 manpage, the MIME::Base64 manpage
  • RFC 1939: Post Office Protocol - Version 3
  • RFC 2195: IMAP/POP AUTHorize Extension for Simple Challenge/Response
  • RFC 2449: POP3 Extension Mechanism

And that's the whole page, bestie. This version is from perl v5.36.0, dated 2022-11-20, and the page itself is Mail::POP3Client(3pm) — go forth and poll your mail like the main character you are. 💅💖✨🦋

📦 where this page comes from