The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mail-Box-2.018
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::POP3

NAME

Mail::Box::POP3 - handle POP3 folders as client

CLASS HIERARCHY

 Mail::Box::POP3
 is a Mail::Box::Net
 is a Mail::Box
 is a Mail::Reporter

SYNOPSIS

 use Mail::Box::POP3;
 my $folder = new Mail::Box::POP3 folder => $ENV{MAIL}, ...;

DESCRIPTION

WARNING: THE POP3 IMPLEMENTAION IS UNDER CONSTRUCTION: IT WILL *NOT* WORK AT ALL!!!!

This documentation describes how POP3 mailboxes work, and what you can do with the POP3 folder object Mail::Box::POP3. Please read Mail::Box-Overview and Mail::Box first.

The internal organization and details are found at the bottom of this manual-page.

METHOD INDEX

Methods prefixed with an abbreviation are described in Mail::Box (MB), Mail::Reporter (MR), Mail::Box::Net (MBN).

The general methods for Mail::Box::POP3 objects:

   MB addMessage  MESSAGE               MB messageId MESSAGE-ID [,MESS...
   MB addMessages MESSAGE [, MESS...    MB messageIds
   MB close OPTIONS                     MB messages ['ALL',RANGE,'ACTI...
   MB copyTo FOLDER, OPTIONS            MB modified [BOOLEAN]
   MB create FOLDERNAME [, OPTIONS]     MB name
   MB current [NUMBER|MESSAGE|MES...       new OPTIONS
   MB delete                            MB openSubFolder NAME [,OPTIONS]
   MR errors                            MR report [LEVEL]
   MB find MESSAGE-ID                   MR reportAll [LEVEL]
   MB listSubFolders OPTIONS            MR trace [LEVEL]
   MB locker                            MR warnings
   MR log [LEVEL [,STRINGS]]            MB writable
   MB message INDEX [,MESSAGE]

The extra methods for extension writers:

   MR AUTOLOAD                          MB openRelatedFolder OPTIONS
   MB DESTROY                           MB organization
   MB appendMessages OPTIONS               popClient
   MB clone OPTIONS                     MB read OPTIONS
   MB coerce MESSAGE                    MB readMessages OPTIONS
   MB determineBodyType MESSAGE, ...    MB scanForMessages MESSAGE, ME...
   MB folderdir [DIR]                   MB sort PREPARE, COMPARE, LIST
   MB foundIn [FOLDERNAME], OPTIONS     MB storeMessage MESSAGE
      getHead MESSAGE                   MB timespan2seconds TIME
      getHeadAndBody MESSAGE            MB toBeThreaded MESSAGES
   MR inGlobalDestruction               MB toBeUnthreaded MESSAGES
   MB lineSeparator [STRING|'CR'|...    MB update OPTIONS
   MR logPriority LEVEL                 MB updateMessages OPTIONS
   MR logSettings                       MB write OPTIONS
   MR notImplemented                    MB writeMessages

METHODS

new OPTIONS

Create a new folder. The are many options which are taken from other objects. For some, different options are set. For POP3-specific options see below, but first the full list.

 OPTION            DEFINED BY         DEFAULT
 access            Mail::Box          'r'
 authenicate       Mail::Box::POP3    'LOGIN'
 create            Mail::Box          0
 folder            Mail::Box          $ENV{MAIL}
 folderdir         Mail::Box          <not used>
 head_wrap         Mail::Box          72
 keep_dups         Mail::Box          0
 extract           Mail::Box          10kB
 lock_type         Mail::Box          <not used>
 lock_file         Mail::Box          <not used>
 lock_timeout      Mail::Box          <not used>
 lock_wait         Mail::Box          <not used>
 log               Mail::Reporter     'WARNINGS'
 password          Mail::Box::Net     undef
 remove_when_empty Mail::Box          <never>
 save_on_exit      Mail::Box          1
 server_name       Mail::Box::Net     undef
 server_port       Mail::Box::Net     110
 trace             Mail::Reporter     'WARNINGS'
 trusted           Mail::Box          0
 username          Mail::Box::Net     undef

Only useful to write extension to Mail::Box::POP3. Common users of folders you will not specify these:

 OPTION            DEFINED BY         DEFAULT
 body_type         Mail::Box::Net     <see Mail::Box::Net>
 body_delayed_type Mail::Box          'Mail::Message::Body::Delayed'
 coerce_options    Mail::Box          []
 field_type        Mail::Box          undef
 head_type         Mail::Box          'Mail::Message::Head::Complete'
 head_delayed_type Mail::Box          'Mail::Message::Head::Delayed'
 locker            Mail::Box          undef
 multipart_type    Mail::Box          'Mail::Message::Body::Multipart'
 manager           Mail::Box          undef
 message_type      Mail::Box          'Mail::Box::POP3::Message'
 realhead_type     Mail::Box          'Mail::Message::Head'

POP3 specific options are described below. For authentications, you have three choices: specify a foldername which resembles an URL, or specify a pop-client object, or separate options for user, password, pop-server and server-port.

  • authenticate => 'LOGIN'|'APOP'

    POP3 can use two methods of authentication: the old LOGIN protocol, which transmits a username and password in plain text, and the newer APOP protocol which uses MD5 encryption. APOP is therefore much better, however not always supported by the server.

  • password => STRING

    The password string for authentication.

  • pop_client => OBJECT

    You may want to specify your own pop-client object. The object which is passed must extend Mail::Transport::POP3.

  • server_name => HOSTNAME

    The HOSTNAME of the POP3 server.

  • server_port => PORTNUMBER

    The PORT behind which the POP3 daemon is running on the pop-server host.

  • username => STRING

    The user's name to login on the POP3 server.

Examples:

 my $pop = Mail::Box::POP3->new('pop3://user:password@pop.xs4all.nl');

 my $pop = $mgr->open(type => 'pop3', user => 'myname',
    password => 'mypassword', server_name => 'pop.xs4all.nl');

METHODS for extension writers

popClient

Returns the pop client object. This does not establish the connection.

getHead MESSAGE

Read the header for the specified message from the remote server.

getHeadAndBody MESSAGE

Read all data for the specified message from the remote server.

IMPLEMENTATION

How POP3-folders work

This implementation

SEE ALSO

Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version 2.018.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.