NAME

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

CLASS INHERITANCE

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

Maintain a folder which has its messages stored on a remote server. The communication between the client application and the server is implemented using the POP3 protocol. This class uses Mail::Transport::POP3 to hide the transport of information, and focusses solely on the correct handling of messages within a POP3 folder.

METHODS

Initiation

new OPTIONS

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.

 OPTION               DEFAULT
 access               'r'
 authenticate         'AUTO'
 body_delayed_type    'Mail::Message::Body::Delayed'
 body_type            'Mail::Message::Body::Lines'
 coerce_options       []
 create               <false>
 extract              10240
 field_type           undef
 folder               <username@server_name>
 folderdir            undef
 head_delayed_type    'Mail::Message::Head::Delayed'
 head_type            'Mail::Message::Head::Complete'
 keep_dups            <false>
 lock_file            <not used>
 lock_timeout         <not used>
 lock_type            'NONE'
 lock_wait            <not used>
 locker               undef
 log                  'WARNINGS'
 manager              undef
 message_type         'Mail::Box::POP3::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 password             undef
 pop_client           undef
 remove_when_empty    <false>
 save_on_exit         <true>
 server_name          undef
 server_port          110
 trace                'WARNINGS'
 trusted              <depends on folder location>
 username             undef

access => MODE

See Mail::Box::new(access)

authenticate => 'LOGIN'|'APOP'|'AUTO'

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. With AUTO, first APOP is tried and if that fails LOGIN.

body_delayed_type => CLASS

See Mail::Box::new(body_delayed_type)

body_type => CLASS|CODE

See Mail::Box::new(body_type)

coerce_options => ARRAY

See Mail::Box::new(coerce_options)

create => BOOLEAN

See Mail::Box::new(create)

extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'

See Mail::Box::new(extract)

field_type => CLASS

See Mail::Box::new(field_type)

folder => FOLDERNAME

See Mail::Box::new(folder)

folderdir => DIRECTORY

See Mail::Box::new(folderdir)

head_delayed_type => CLASS

See Mail::Box::new(head_delayed_type)

head_type => CLASS

See Mail::Box::new(head_type)

keep_dups => BOOLEAN

See Mail::Box::new(keep_dups)

lock_file => FILENAME

See Mail::Box::new(lock_file)

lock_timeout => SECONDS

See Mail::Box::new(lock_timeout)

lock_type => CLASS|STRING

See Mail::Box::new(lock_type)

lock_wait => SECONDS

See Mail::Box::new(lock_wait)

locker => OBJECT

See Mail::Box::new(locker)

log => LEVEL

See Mail::Reporter::new(log)

manager => MANAGER

See Mail::Box::new(manager)

message_type => CLASS

See Mail::Box::new(message_type)

multipart_type => CLASS

See Mail::Box::new(multipart_type)

password => STRING

See Mail::Box::Net::new(password)

pop_client => OBJECT

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

remove_when_empty => BOOLEAN

See Mail::Box::new(remove_when_empty)

save_on_exit => BOOLEAN

See Mail::Box::new(save_on_exit)

server_name => HOSTNAME

See Mail::Box::Net::new(server_name)

server_port => INTEGER

See Mail::Box::Net::new(server_port)

trace => LEVEL

See Mail::Reporter::new(trace)

trusted => BOOLEAN

See Mail::Box::new(trusted)

username => STRING

See Mail::Box::Net::new(username)

Examples:

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

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

Opening folders

clone OPTIONS

See Mail::Box::clone()

create FOLDERNAME, OPTIONS

See Mail::Box::create()

folderdir [DIRECTORY]

See Mail::Box::folderdir()

foundIn [FOLDERNAME], OPTIONS

See Mail::Box::foundIn()

On open folders

addMessage MESSAGE

See Mail::Box::addMessage()

addMessages MESSAGE [, MESSAGE, ...]

See Mail::Box::addMessages()

copyTo FOLDER, OPTIONS

See Mail::Box::copyTo()

modified [BOOLEAN]

See Mail::Box::modified()

name

See Mail::Box::name()

organization

See Mail::Box::organization()

type

See Mail::Box::type()

update OPTIONS

See Mail::Box::update()

url

See Mail::Box::url()

writable

See Mail::Box::writable()

Closing the folder

DESTROY

See Mail::Box::DESTROY()

close OPTIONS

See Mail::Box::close()

delete

See Mail::Box::delete()

The messages

current [NUMBER|MESSAGE|MESSAGE-ID]

See Mail::Box::current()

find MESSAGE-ID

See Mail::Box::find()

message INDEX [,MESSAGE]

See Mail::Box::message()

messageId MESSAGE-ID [,MESSAGE]

See Mail::Box::messageId()

messageIds

See Mail::Box::messageIds()

messages ['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER]

See Mail::Box::messages()

scanForMessages MESSAGE, MESSAGE-IDS, TIMESTAMP, WINDOW

See Mail::Box::scanForMessages()

Sub-folders

listSubFolders OPTIONS

See Mail::Box::listSubFolders()

openRelatedFolder OPTIONS

See Mail::Box::openRelatedFolder()

openSubFolder NAME, OPTIONS

See Mail::Box::openSubFolder()

Message threads [internals]

toBeThreaded MESSAGES

See Mail::Box::toBeThreaded()

toBeUnthreaded MESSAGES

See Mail::Box::toBeUnthreaded()

Reading and Writing [internals]

appendMessages OPTIONS

See Mail::Box::appendMessages()

coerce MESSAGE

See Mail::Box::coerce()

determineBodyType MESSAGE, HEAD

See Mail::Box::determineBodyType()

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.

lineSeparator [STRING|'CR'|'LF'|'CRLF']

See Mail::Box::lineSeparator()

locker

See Mail::Box::locker()

popClient

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

read OPTIONS

See Mail::Box::read()

readMessages OPTIONS

See Mail::Box::readMessages()

storeMessage MESSAGE

See Mail::Box::storeMessage()

updateMessages OPTIONS

See Mail::Box::updateMessages()

write OPTIONS

See Mail::Box::write()

writeMessages

See Mail::Box::writeMessages()

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

timespan2seconds TIME

See Mail::Box::timespan2seconds()

IMPLEMENTATION

How POP3-folders work

This implementation

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Written by Liz Mattijsen (liz@dijkmat.nl) and Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.029.

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

cpanm Mail::Box

perl -MCPAN -e shell
install Mail::Box