The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Mail::Message::Replace::MailInternet - fake Mail::Internet

INHERITANCE

 Mail::Message::Replace::MailInternet
   is a Mail::Message
   is a Mail::Reporter

SYNOPSIS

 !!! VERY ALPHA CODE !!!

 # change
 use Mail::Internet;
 # into
 use Mail::Message::Replace::MailInternet;
 # in existing code, and the code should still work, but
 # with the Mail::Message features.

DESCRIPTION

This module is a wrapper around a Mail::Message, which simulates a Mail::Internet object. The name-space of that module is hijacked and many methods are added.

Most methods will work without any change, but you may need to have a look at your smtpsend() and send() calls.

OVERLOADED

METHODS

Constructors

$obj->clone

Mail::Message::Replace::MailInternet->coerce(MESSAGE)

    Coerce (adapt type) of the specified MESSAGE (anything Mail::Message::coerce() accepts) into an Mail::Internet simulating object.

$obj->dup

    Duplicate the message. The result will again be a Mail::Internet compatible object.

$obj->empty

    Remove all data from this object. Very dangerous!

Mail::Message::Replace::MailInternet->new([ARG], [OPTIONS])

     Option      Defined in       Default                                                                 
     Body                         C<undef>                                                                
     FoldLength                   79                                                                      
     Header                       C<undef>                                                                
     MailFrom                     C<'KEEP'>                                                               
     Modify                       0                                                                       
     body        L<Mail::Message>  undef                                                                   
     body_type   L<Mail::Message>  L<Mail::Message::Body::Lines|Mail::Message::Body::Lines>                
     deleted     L<Mail::Message>  <false>                                                                 
     field_type  L<Mail::Message>  undef                                                                   
     head        L<Mail::Message>  undef                                                                   
     head_type   L<Mail::Message>  L<Mail::Message::Replace::MailHeader|Mail::Message::Replace::MailHeader>
     labels      L<Mail::Message>  {}                                                                      
     log         L<Mail::Reporter>  C<'WARNINGS'>                                                           
     messageId   L<Mail::Message>  undef                                                                   
     modified    L<Mail::Message>  <false>                                                                 
     trace       L<Mail::Reporter>  C<'WARNINGS'>                                                           
     trusted     L<Mail::Message>  <false>                                                                 

    . Body ARRAY-OF-LINES

      Array of "\n" terminated lines. If not specified, the lines will be read from ARG.

    . FoldLength INTEGER

    . Header OBJECT

      The Mail::Header object, which is passed here, is a fake one as well... It is translated into a new(head). If not given, the header will be parsed from the ARG.

    . MailFrom 'IGNORE'|'ERROR'|'COERCE'|'KEEP'

    . Modify BOOLEAN

    . body OBJECT

    . body_type CLASS

    . deleted BOOLEAN

    . field_type CLASS

    . head OBJECT

    . head_type CLASS

    . labels ARRAY|HASH

    . log LEVEL

    . messageId STRING

    . modified BOOLEAN

    . trace LEVEL

    . trusted BOOLEAN

    Example: replace traditional Mail::Internet by this wrapper

      # was
      use Mail::Internet;
      my $mi = Mail::Internet->new(@options);
    
      # becomes
      use Mail::Message::Replace::MailInternet;
      my $mi = Mail::Internet->new(@options);

Attributes

$obj->MailFrom([STRING])

    Your email address.

Constructing a message

$obj->add_signature([FILENAME])

    Replaced by sign(), but still usable. FILENAME is the file which contains the signature, which defaults to $ENV{HOME}/.signature.

$obj->bounce([RG-OBJECT|OPTIONS])

Mail::Message::Replace::MailInternet->build([MESSAGE|BODY], CONTENT)

Mail::Message::Replace::MailInternet->buildFromBody(BODY, [HEAD], HEADERS)

$obj->extract(ARRAY or FILEHANDLE)

    Read header and body from an ARRAY or FILEHANDLE

$obj->forward(OPTIONS)

$obj->forwardAttach(OPTIONS)

$obj->forwardEncapsulate(OPTIONS)

$obj->forwardInline(OPTIONS)

$obj->forwardNo(OPTIONS)

$obj->forwardPostlude

$obj->forwardPrelude

$obj->forwardSubject(STRING)

$obj->read(ARRAY|FILEHANDLE, OPTIONS)

Mail::Message::Replace::MailInternet->read(ARRAY|FILEHANDLE, OPTIONS)

    Read header and body from the specified ARRAY or FILEHANDLE. When used as object method, Mail::Message::read() is called, to be MailBox compliant. As class method, the Mail::Internet compatible read is called. OPTIONS are only available in the first case.

     Option               Defined in                         Default
     strip_status_fields  L<Mail::Message::Construct::Read>  <true> 

    . strip_status_fields BOOLEAN

$obj->read_body(ARRAY|FILEHANDLE)

    Read only the message's body from the ARRAY or FILEHANDLE.

$obj->read_header(ARRAY|FILEHANDLE)

    Read only the message's header from the ARRAY or FILEHANDLE

$obj->rebuild(OPTIONS)

$obj->reply(OPTIONS)

    BE WARNED: the main job for creating a reply is done by Mail::Message::reply(), which may produce a result which is compatible, but may be different from Mail::Internet's version.

     Option           Defined in       Default                                                                   
     Bcc              L<Mail::Message::Construct::Reply>  undef                                                                     
     Cc               L<Mail::Message::Construct::Reply>  <'cc' in current>                                                         
     Exclude                           []                                                                        
     From             L<Mail::Message::Construct::Reply>  <'to' in current>                                                         
     Inline                            E<gt>                                                                     
     Keep                              []                                                                        
     Message-ID       L<Mail::Message::Construct::Reply>  <uniquely generated>                                                      
     ReplyAll                          <false>                                                                   
     Subject          L<Mail::Message::Construct::Reply>  L<replySubject()|Mail::Message::Construct::Reply/"Constructing a message">
     To               L<Mail::Message::Construct::Reply>  <sender in current>                                                       
     body             L<Mail::Message::Construct::Reply>  undef                                                                     
     group_reply      L<Mail::Message::Construct::Reply>  <true>                                                                    
     header_template                   C<$ENV{HOME}/.mailhdr>                                                    
     include          L<Mail::Message::Construct::Reply>  C<'INLINE'>                                                               
     max_signature    L<Mail::Message::Construct::Reply>  C<10>                                                                     
     message_type     L<Mail::Message::Construct::Reply>  L<Mail::Message|Mail::Message>                                            
     postlude         L<Mail::Message::Construct::Reply>  undef                                                                     
     prelude          L<Mail::Message::Construct::Reply>  undef                                                                     
     quote            L<Mail::Message::Construct::Reply>  'E<gt> '                                                                  
     signature        L<Mail::Message::Construct::Reply>  undef                                                                     
     strip_signature  L<Mail::Message::Construct::Reply>  C<qr/^--\s/>                                                              

    . Bcc ADDRESSES

    . Cc ADDRESSES

    . Exclude ARRAY-OF-NAMES

      Remove the fields witht the specified names from the produced reply message.

    . From ADDRESSES

    . Inline STRING

      Quotation STRING, which is translated into reply(quote). The normal default of quote is "> ", in stead of ">".

    . Keep ARRAY-OF-NAMES

      Copy all header fields with the specified NAMES from the source to the reply message.

    . Message-ID STRING

    . ReplyAll BOOLEAN

      Reply to the group? Translated into reply(group_reply), which has as default the exact oposite of this option, being true.

    . Subject STRING|CODE

    . To ADDRESSES

    . body BODY

    . group_reply BOOLEAN

    . header_template FILENAME|undef

      Read the return header from the template file. When this is explicitly set to undef, or the file does not exist, then a header will be created.

    . include 'NO'|'INLINE'|'ATTACH'

    . max_signature INTEGER

    . message_type CLASS

    . postlude BODY|LINES

    . prelude BODY|LINES

    . quote CODE|STRING

    . signature BODY|MESSAGE

    . strip_signature REGEXP|STRING|CODE

$obj->replyPrelude([STRING|FIELD|ADDRESS])

$obj->replySubject(STRING)

Mail::Message::Replace::MailInternet->replySubject(STRING)

$obj->sign(OPTIONS)

    Add a signature (a few extra lines) to the message.

     Option     Defined in       Default 
     File                        C<undef>
     Signature                   ''      

    . File FILENAME

      Specifies a filename where the signature is in.

    . Signature STRING|ARRAY-OF-LINES

      The signature in memory.

The Message

$obj->container

$obj->isDummy

$obj->isPart

$obj->messageId

$obj->nntppost(OPTIONS)

    Send an NNTP message (newsgroup message), which is equivalent to Mail::Transport::NNTP or Mail::Message::send() with via 'nntp'.

     Option  Defined in       Default           
     Debug                    <false>           
     Host                     <from Net::Config>
     Port                     119               

    . Debug BOOLEAN

    . Host HOSTNAME

    . Port INTEGER

$obj->print([FILEHANDLE])

    Prints the whole message to the specified FILEHANDLE, which default to STDOUT. This calls Mail::Message::print().

$obj->send(TYPE, OPTIONS)

    Send via Mail Transfer Agents (MUA). These will be handled by various Mail::Transport::Send extensions. The test TYPE is not supported.

$obj->size

$obj->toplevel

$obj->write([FILEHANDLE])

The header

$obj->add(LINES)

    Add header lines, which simply calls Mail::Message::Head::add() on the header for each specified LINE. The last added LINE is returned.

$obj->bcc

$obj->cc

$obj->clean_header

$obj->combine(TAG, [WITH])

    Not implemented, because I see no use for it.

$obj->date

$obj->delete(NAME, [INDEX]])

$obj->destinations

$obj->fold([LENGTH])

$obj->fold_length([[TAG], LENGTH])

$obj->from

$obj->get(NAME, [INDEX])

    Get all the header fields with the specified NAME. In scalar context, only the first fitting NAME is returned. Even when only one NAME is specified, multiple lines may be returned: some fields appear more than once in a header. Calls Mail::Message::Replace::MailHeader::get()

$obj->guessTimestamp

$obj->head([HEAD])

    Returns the head of the message, or creates an empty one if none is defined. The HEAD argument, which sets the header, is not available for Mail::Internet, but is there to be compatible with the head method of Mail::Message.

$obj->header([ARRAY])

$obj->nrLines

$obj->print_header(FILEHANDLE)

$obj->replace(TAG, LINE, [INDEX])

$obj->sender

$obj->study(FIELDNAME)

$obj->subject

$obj->tidy_headers

    No effect anymore (always performed).

$obj->timestamp

$obj->to

The body

$obj->body([ARRAY-OF-LINES|LIST-OF-LINES])

    Returns an array of lines, representing the body. With arguments, a new body will be created. In Mail::Internet, the body is not an object but a simple array.

    BE WARNED: this overrules the Mail::Message::body() method, which may cause some confusion. Use bodyObject() to get access to that body's data.

$obj->bodyObject([BODY])

$obj->decoded(OPTIONS)

$obj->encode(OPTIONS)

$obj->isMultipart

$obj->isNested

$obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])

$obj->print_body([FILEHANDLE])

$obj->remove_sig([NRLINES])

$obj->smtpsend(OPTIONS)

    This method is calling Mail::Message::send() via smtp, which is implemented in Mail::Transport::SMTP. The implementation is slightly different, so this method is not 100% compliant.

     Option    Defined in       Default                               
     Debug                      <false>                               
     Hello                      <helo_domain from Net::Config>        
     Host                       C<$ENV{SMTPHOSTS} or from Net::Config>
     MailFrom                   C<$ENV{MAILADDRESS}> or $ENV{USER}    
     Port                       25                                    

    . Debug BOOLEAN

    . Hello STRING

    . Host HOSTNAME

      Only the first detected HOSTNAME is taken, so differs from the original implementation.

    . MailFrom STRING

      Your e-mail address. This simulated Mail::Internet object does not try to create an e-mail address from the sendmail configuration file, because that is generally a bad idea in environments with virtual hosts, as we have now-adays.

    . Port INTEGER

$obj->tidy_body

    Removes blank lines from begin and end of the body.

Flags

$obj->deleted([BOOLEAN])

$obj->isDeleted

$obj->isModified

$obj->label(LABEL|PAIRS)

$obj->labels

$obj->labelsToStatus

$obj->modified([BOOLEAN])

$obj->statusToLabels

The whole message as text

$obj->as_mbox_string

    Returns the whole message as one string, which can be included in an MBOX folder (while not using Mail::Box::Mbox). The Content-Length header field is removed and lines in the body which start with From are escaped with an >.

$obj->file

$obj->lines

$obj->printStructure([FILEHANDLE][, INDENT])

$obj->string

Internals

$obj->isDelayed

$obj->readBody(PARSER, HEAD [, BODYTYPE])

$obj->readFromParser(PARSER, [BODYTYPE])

$obj->readHead(PARSER [,CLASS])

$obj->recursiveRebuildPart(PART, OPTIONS)

$obj->storeBody(BODY)

$obj->takeMessageId([STRING])

Error handling

$obj->AUTOLOAD

$obj->addReport(OBJECT)

$obj->defaultTrace([LEVEL, [LEVEL])

Mail::Message::Replace::MailInternet->defaultTrace([LEVEL, [LEVEL])

$obj->errors

$obj->log([LEVEL [,STRINGS]])

Mail::Message::Replace::MailInternet->log([LEVEL [,STRINGS]])

$obj->logPriority(LEVEL)

Mail::Message::Replace::MailInternet->logPriority(LEVEL)

$obj->logSettings

$obj->notImplemented

$obj->report([LEVEL])

$obj->reportAll([LEVEL])

$obj->shortSize([VALUE])

Mail::Message::Replace::MailInternet->shortSize([VALUE])

$obj->shortString

$obj->trace([LEVEL])

$obj->warnings

Cleanup

$obj->DESTROY

$obj->destruct

$obj->inGlobalDestruction

The nasty bits

$obj->isa(CLASS)

Mail::Message::Replace::MailInternet->isa(CLASS)

    Of course, the isa() class inheritance check should not see our nasty trick.

DIAGNOSTICS

Error: Cannot include forward source as $include.

Unknown alternative for the forward(include). Valid choices are NO, INLINE, ATTACH, and ENCAPSULATE.

Error: Mail::Internet does not support this kind of data

The ARGS data can only be a file handle or an ARRAY. Other data types are not supported (see read() if you want to have more).

Error: No address to create forwarded to.

If a forward message is created, a destination address must be specified.

Error: Package $package does not implement $method.

Fatal error: the specific package (or one of its superclasses) does not implement this method where it should. This message means that some other related classes do implement this method however the class at hand does not. Probably you should investigate this and probably inform the author of the package.

Error: forwardAttach requires a preamble object

Error: forwardEncapsulate requires a preamble object

Error: no rebuild rule $name defined.

DETAILS

REFERENCES

See the MailBox website at http://perl.overmeer.net/mailbox/ for more details.

COPYRIGHTS

Distribution version 2.054. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.

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