Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZConf::Mail(3)	      User Contributed Perl Documentation	ZConf::Mail(3)

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:

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=ZConf-Mail>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/ZConf-Mail>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/ZConf-Mail>

       o   Search CPAN

	   <http://search.cpan.org/dist/ZConf-Mail>

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.

perl v5.24.1			  2011-07-02			ZConf::Mail(3)

NAME | VERSION | SYNOPSIS | METHODES | ERROR RELATED METHODS | VARIABLES | ERROR CODES | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ZConf::Mail&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help