The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
ZConf-Mail-2.0.0
River stage zero No dependents
++
/ ZConf::Mail

NAME

ZConf::Mail - Misc mail client functions backed by ZConf.

VERSION

Version 2.0.0

SYNOPSIS

    use ZConf::Mail;

    my $zcmail = ZConf::Mail->new();
    ...

METHODES

Any time you see account name or account, referenced outside of 'createAccount', it means that it should also include the type as well. So for a POP3 account named 'test' it would be 'pop3/test'.

new

This initiates the module. The one arguement is accepted and it is a hash.

hash keys

zconf

This can be allows one to pass ZConf a specific set of arguements to be initialized with.

accountExists

Checks to make sure a accont exists. One arguement is taken and that is the account name.

    if($zcmail->accountExists('pop3/foo)){
        print "pop3/foo does exist";
    }

connectIMAP

This connects Mail::IMAPTalk connection to a IMAP account.

    #connects to the IMAP account 'imap/foo'
    my $imap=$zcmail->connectIMAP('imap/foo');
    if($zcmail->error)(
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    )

connectMaildir

Creates a new Mail::Box::Maildir object for accessing the maildir.

    #connects to the maildir account 'maildir/foo'
    my $imap=$zcmail->connectMaildir('maildir/foo');
    if($zcmail->error)(
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    )

connectMbox

Creates a new Mail::Box::Mbox object for accessing the mbox.

    #connects to the mbox account 'mbox/foo'
    my $imap=$zcmail->connectMbox('mbox/foo');
    if($zcmail->error)(
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    )

connectPOP3

This connects Mail::POP3Client connection to a POP3 account.

    #connects to the mbox account 'pop3/foo'
    my $imap=$zcmail->connectPOP3('pop3/foo');
    if($zcmail->error)(
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    )

connectSMTP

This connects Mail::POP3Client connection to a POP3 account.

    #connects to the SMTP account 'smtp/foo'
    my $imap=$zcmail->connectSMTP('smtp/foo');
    if($zcmail->error)(
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    )

createAccount

This creates a new account. The only arguement accepted, and required, is a hash. More information can be found below.

args hash

The required variables for a account can be found in the VARIABLES section. Those listed below are also required by this function.

The two common ones are 'type' and 'account'. You should consult 'VARIABLES' for the various posibilities for each account type.

type

This is the type of a account it is. It is always lower case as can be seen in the variables section.

account

This is the name of the account. It will be appended after the account type. Thus for the account 'pop3/some account name' it will be 'some account name'.

    #adds a POP3 server
    $zcmail->createAccount({type=>'pop3',
                            account=>'some account name',
                            user=>'monkey',
                            pass=>'ape',
                            auth=>'auto',
                            useSSL=>'0',
                            SSLoptions=>'',
                            deliverTo=>'',
                            fetchable=>'0',
                            server=>'127.0.0.1',
                            });
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

createEmailSimple

Creates a new Email::Simple object.

function args

account

This is the account is being setup for. If this is not specified, the default one is used.

to

An array of To addresses.

cc

An array of CC addresses.

subject

The subject of the message.

body

The body of the message.

createMimeLite

This create a new MIME::Lite object.

This will also sign it if needed be.

args hash reference

The three following are required.

    account
    subject
    body

account

This is the account is being setup for. If no account is specified, the default on is used.

to

An array of To addresses.

cc

An array of CC addresses.

subject

The subject of the message.

body

The body of the message.

files

An array of files to attach.

in-reply-to

This will set the in-reply-to header value.

dontSign

If is set to true and the account is set to sign by default, it won't be.

quiet

When created, call the quiet method.

This defaults to on as it will throw errors when doing GPG signing.

defaultFetchableGet

This sets the default sendable email address.

    my $defaultFetchable=$zcmail->defaultFetchableGet;
    if(!defined($defaultFetchable)){
        print "There is no default sendable account.\n";
    }
    
    print $defaultFetchable."\n";

defaultFetchableSet

This sets the default fetchable account.

    $zcmail->defaultFechableSet('smtp/foo');
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

defaultSendableGet

This sets the default sendable email account.

    my $defaultSendable=$zcmail->defaultSendableGet;
    if(!defined($defaultSendable)){
        print "There is no default sendable account.\n";
    }
    
    print $defaultSendable."\n";

defaultSendableSet

This sets the default sendable email address.

    $zcmail->defaultSendableSet('smtp/foo');
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

defaultImapGet

This gets what the default IMAP account is.

defaultImapSet

This gets what the default IMAP account is.

delAccount

This is used for removed a account. One option is taken and that is the name of the account.

   #removes the account 'mbox/foo'
   $zcmail->delAccount('mbox/foo');
   if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
   }

deliverable

This checks if a acocunt is deliverable or not.

    #check to see if the account is a account that can be delivered to
    if(!zcmail->deliverable('exec/foo')){
        print "Not deliverable.";
    }

deliver

This is a wrapper function to the other deliver functions. This is a wrapper to the other delivery functions.

The first arguement is the account. The second is the message. The third is the a hash that some deliver types optionally use.

args hash

folder

This can be used to specify a folder to deliver to. If it is not defined, it will try to use what ever is the inbox for that account.

Currently this is only used by IMAP.

    #delivers the mail contained in $mail to 'exec/foo'
    $zcmail->deliver('exec/foo', $mail);
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

    #delivers the mail contained in $mail to 'imap/foo' to the 'foo.bar'
    $zcmail->deliver('imap/foo', $mail, {folder=>'foo.bar'});
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

deliverExec

This is a delivers to a exec account.

It is generally not best to call it directly, but to let the deliver function route it. This allows for more flexible delivery.

The first arguement is the account. The second is the message. The third is the a optional args hash.

    #delivers the mail contained in $mail to 'exec/foo'
    $zcmail->deliverExec('exec/foo', $mail);
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

deliverIMAP

This is a delivers to a IMAP account.

It is generally not best to call it directly, but to let the deliver function route it. This allows for more flexible delivery.

    #delivers the mail contained in $mail to 'imap/foo' to the inbox
    $zcmail->deliverIMAP('imap/foo', $mail);
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

    #delivers the mail contained in $mail to 'imap/foo' to the 'foo.bar'
    $zcmail->deliverIMAP('imap/foo', $mail, {folder=>'foo.bar'});
    if($zcmail->{error}){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

fetch

This is a wrapper function for the other accounts. The only accepted arg is account name. If no account is specified, the default one is used.

It is then delivered to the account specified by variable 'deliverTo' for the account.

    #fetches the mail for 'pop3/foo'
    $zcmail->fetch('pop3/foo');
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

fetchable

This checks if a account is fetchable or not. The reason for the existance it to make some things look neater.

fetchIMAP

Fetches the messages from the inbox of a IMAP account.

    my $number=$mail->fetchIMAP('imap/foo');
    if($mail->error}){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }else{
        print 'Fetched '.$number."messages.\n";
    }

fetchMaildir

Fetches the messages from the inbox of a maildir account.

    my $number=$mail->fetchMaildir('maildir/foo');
    if($mail->{error}}){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }else{
        print 'Fetched '.$number."messages.\n";
    }

fetchMbox

Fetches the messages from the inbox of a mbox account.

    my $number=$mail->fetchMbox('mbox/foo');
    if($mail->{error}}){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }else{
        print 'Fetched '.$number."messages.\n";
    }

fetchPOP3

Fetches the messages from the inbox of a POP3 account.

    my $number=$mail->fetchPOP3('pop3/foo');
    if($mail->{error}}){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }else{
        print 'Fetched '.$number."messages.\n";
    }

formatter

Automatically format a chunk of text against various settings, primarily line wrapping.

    $text=$zcmail->formatter($text);
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

formatterGetAll

Get all options for the formatter.

    my %formatterOptions=$zcmail->formatterGetAll;
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }else{
          print 'marginLeft:'.formatterOptions{marginLeft}."\n".
                'marginRight:'.formatterOptions{marginRight}."\n".
                'squeeze:'.formatterOptions{squeeze}."\n".
                'ignore:'.formatterOptions{ignore}."\n".
                'justify:'.formatterOptions{justify}."\n".
                'tabspace:'.formatterOptions{tabspace}."\n";
    }

formatterSet

Set some options for the formatter.

Two arguments are required.

The first is the option to operate on.

The second is the value. A value of undef will result it being removed, there for the default being used when formatterGetAll is called.

    #set the text justification to the right
    $zcmail->formatterSet('justify', 'right');
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

    #set the text justification back to the default
    $zcmail->formatterSet('justify', undef);
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

getAccounts

Gets a array of the various accounts.

    my @accounts=$zcmail->getAccounts;
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

getAccountArgs

This gets the various variables for a account, with 'accounts/*/*/' removed.

One arguement is required and that is the account name.

    #get the account args for 'pop3/foo'
    my %args=$zcmail->getAccountArgs('pop3/foo');
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

getSet

This gets what the current set is.

    my $set=$zcmail->getSet;
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

init

This is used for initiating the config used by ZConf.

    $zcmail->init;
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

listSets

This lists the available sets.

    my @sets=$zcmail->listSets;
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

modAccount

Modifies a account.

args hash

Outside of account type, the rest are variables that will be changed.

type

This is the type of a account it is. It is always lower case as can be seen in the variables section.

account

This is the name of the account. It will be appended after the account type. Thus for the account 'pop3/some account name' it will be 'some account name'.

readSet

This reads a specific set. If the set specified is undef, the default set is read.

    #read the default set
    $zcmail->readSet();
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

    #read the set 'someSet'
    $zcmail->readSet('someSet');
    if($zcmail->error){
        warn('Error:'.$zcmail->error.': '.$zcmail->errorString);
    }

send

This sends a email. One arguement is accepted and that is a hash.

args hash

account

This is the account it is sending for. If this is not specified, the default sendable account is used.

to

This is a array of to addresses.

cc

This is a array of cc addresses.

bcc

This is a array of bcc addresses.

mail

This is the raw mail message to send.

save

This will override if a sent message will be saved or not.

sendable

Checks to see if a sendable.

    #checks to see if 'smtp/foo' is sendable
    if(!$zcmail->sendable('smtp/foo')){
        print 'not sendable'
    }

sign

This signs the body.

There are three required arguements. The first is the account name it will be sending from. The second the body of the email. The third is the to address.

ERROR RELATED METHODS

error

Returns the current error code and true if there is an error.

If there is no error, undef is returned.

    if($zconf->error){
                warn('error: '.$zconf->error.":".$zconf->errorString);
    }

errorBlank

This blanks the error storage and is only meant for internal usage.

It does the following.

    $self->{error}=undef;
    $self->{errorString}="";

errorString

Returns the error string if there is one. If there is not, it will return ''.

    if($zconf->error){
                warn('error: '.$zconf->error.":".$zconf->errorString);
    }

VARIABLES

In the various sections below, '*' is used to represent the name of a account. Account names can't match the following.

        undef
        /\//
        /^\./
        /^ /
        / $/
        /\.\./

POP3

accounts/pop3/*/user

This is the username for a POP3 account.

accounts/pop3/*/pass

This is the password for a POP3 account.

accounts/pop3/*/useSSL

If set to a boolean value of true, SSL will be used.

accounts/pop3/*/deliverTo

This is the account to deliver to.

accounts/imap/*/deliverToFolder

This is the folder in the account to deliver to.

accounts/pop3/*/fetchable

If this account should be considered fetchable. If this flag is set, this will not be fetched my 'Mail::ZConf::Fetch'.

accounts/pop3/*/auth

This is the auth type to use with the POP3 server.

accounts/pop3/*/server

The POP3 server to use.

accounts/pop3/*/port

The port on the server to use.

IMAP

accounts/imap/*/

Any thing under here under here is a IMAP account.

accounts/imap/*/user

This is the username for a IMAP account.

accounts/imap/*/pass

This is the password for a IMAP account.

accounts/imap/*/useSSL

If set to a boolean value of true, SSL will be used.

accounts/imap/*/deliverTo

This is the account to deliver to.

accounts/imap/*/deliverToFolder

This is the folder in the account to deliver to.

accounts/imap/*/fetchable

If this account should be considered fetchable. If this flag is set, this will not be fetched my 'ZConf::Mail::Fetch', not written yet.

This should be set if you are planning on using it for storage.

accounts/imap/*/inbox

This is the inbox that the mail should be delivered to.

accounts/imap/*/server

The IMAP server to use.

accounts/imap/*/port

The port on the server to use.

MBOX

accounts/mbox/*/mbox

This is the MBOX file to use.

accounts/mbox/*/deliverTo

This is the account to deliver to.

accounts/mbox/*/fetchable

If this account should be considered fetchable. If this flag is set, this will not be fetched my 'ZConf::Mail::Fetch', not written yet.

Maildir

accounts/maildir/*/maildir

This is the MBOX file to use.

accounts/maildir/*/deliverTo

This is the account to deliver to.

accounts/imap/*/deliverToFolder

This is the folder in the account to deliver to.

accounts/maildir/*/fetchable

If this account should be considered fetchable. If this flag is set, this will not be fetched my 'ZConf::Mail::Fetch', not written yet.

SMTP

accounts/smtp/*/user

This is the username for a SMTP account.

accounts/smtp/*/pass

This is the password for a SMTP account.

accounts/smtp/*/auth

This is the auth type to use with the SMTP server.

accounts/smtp/*/server

The SMTP server to use.

accounts/smtp/*/port

The port on the server to use.

accounts/smtp/*/useSSL

If set to a boolean value of true, SSL will be used.

accounts/smtp/*/from

The from address to use for a account.

accounts/smtp/*/name

The name that will be used with the account.

accounts/smtp/*/saveTo

This is the account to save it to. If it not defined or blank, it will not saved.

accounts/smtp/*/saveToFolder

This is the folder to save it to for the account.

accounts/smtp/*/timeout

The time out for connecting to the server.

accounts/smtp/*/usePGP

If PGP should be used or not for this account. This is a Perl boolean value.

accounts/smtp/*/pgpType

clearsign

Clear sign the message.

mimesign

Attach the signature as a attachment.

signencrypt

Sign and encrypt the message. Not yet implemented.

accounts/smtp/*/PGPkey

The PGP key to use.

accounts/smtp/*/PGPdigestAlgo

The digest algorithym to use. It will default to 'SHA512' if not specified.

To find what out what your version supports, run 'gpg --version'.

EXEC

deliver

This is the command to execute for delivering a mail message. A single message will be delivered at a time by running the specified program and piping the message into it. Only a single message is delivered at once.

A example would be setting this to '/usr/local/libexec/dovecot/deliver' to deliver a message one's dovecot account.

FORMATTER

formatter/marginLeft

This is the left margin. The default is zero if this is not defined.

formatter/marginRight

This is the right margin. The default is 72 if this is not defined.

formatter/squeeze

Removes unneeded whitespace. This is on by default.

formatter/ignore

Don't reformat any paragraph that matches this line. The default is '^[ \t]'.

formatter/justify

How to justify the text. The default is left.

formatter/tabspace

This is the default spaces per tab. The default is '4'.

MISC

default/sendable

This is the default sendable account. If this key does not exist or set to '', there is no default sendable account.

default/fetchable

This is the default fetchable account. If this key does not exist or set to '', there is no default fetchable account.

INTERNAL VARIABLES

$zcmail->{init}

If this is false, '$zcmail->init' needs run.

$zcmail->{legal}

This hashes which contains the legal values for each type in a array. So for SMTP, '$zcmail->{legal}{smtp}' contains the array of legal values for SMTP.

$zcmail->{required}

This hashes which contains the required values for each type in a array. So for SMTP, '$zcmail->{required}{smtp}' contains the array of required values for SMTP.

$zcmail->{fetchable}

This contains a array of fetchable account types.

$zcmail->{deliverable}

This contains a array of deliverable account types.

$zcmail->{sendable}

This contains a array of sendable account types.

ERROR CODES

If any funtion errors, the error code is writen to '$zcmail->{error}', a error message is printed to stderr, and a short description is put in '$zcmail->{errorString}'.

When no error is present '$zcmail->{error}' is false, specifically undef.

1

Could not create the config.

2

No account type specified.

3

Unknown account type specified.

4

Illegal account name.

5

A required variable is not defined.

6

Account does not exist.

7

Authenticating with the POP3 server failed.

8

Connecting to the POP3 server failed.

9

Failed to either connect to IMAP server or authenticate with it.

10

Failed to connect to SMTP server.

11

Failed to authenticate with the SMTP server.

12

Failed to send the from for the SMTP session.

13

Failed to authenticate or connect to the SMTP server.

14

Failed to access maildir.

15

Account is not fetchable.

16

Failed to connect to POP3.

17

POP3 fetch failed.

18

Failed to read a ZConf config.

19

Wrong account type.

20

IO::MultiPipe error. See the error string for detains on it.

21

Mbox message delete failed.

22

Mbox fetch failed.

23

IMAP folder select failed.

24

Account is not a sendable account type.

25

No To or CC defined.

26

Failed to send a To, CC, or BCC address.

27

Failed to start the data session.

28

Failed to send the data.

29

Failed to end the data session.

30

Failed to quit.

31

Failed to create a Email::Simple object.

32

The account has one or more missing variables.

33

No INBOX specified for the IMAP account.

34

Failed to selected IMAP folder.

35

Failed to append to the IMAP folder.

36

ZConf error.

37

'saveTo' is not enabled for this account. This means it is either undefined or set to ''.

38

File does not exist.

39

Failed to create temporary directory for signing.

40

Failed to create temprorary body file for signing.

41

No pgpType is not specified.

42

PGPGkey is not specified.

43

Sign type is not valid.

44

Signing failed.

45

The specified option is not a valid option.

AUTHOR

Zane C. Bowers, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-zconf-mail at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ZConf-Mail. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc ZConf::Mail

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Zane C. Bowers, all rights reserved.

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