###########
EmailParser
###########


****
NAME
****


Kernel::System::EmailParser - parse and encode an email


***********
DESCRIPTION
***********


A module to parse and encode an email.


****************
PUBLIC INTERFACE
****************


new()
=====


create an object. Do not use it directly, instead use:


.. code-block:: perl

     use Kernel::System::EmailParser;
 
     # as string (takes more memory!)
     my $ParserObject = Kernel::System::EmailParser->new(
         Email        => $EmailString,
         Debug        => 0,
     );
 
     # as stand alone mode, without parsing emails
     my $ParserObject = Kernel::System::EmailParser->new(
         Mode         => 'Standalone',
         Debug        => 0,
     );



GetPlainEmail()
===============


To get a email as a string back (plain email).


.. code-block:: perl

     my $Email = $ParserObject->GetPlainEmail();



GetParam()
==========


To get a header (e. g. Subject, To, ContentType, ...) of an email
(mime is already done!).


.. code-block:: perl

     my $To = $ParserObject->GetParam( WHAT => 'To' );



GetEmailAddress()
=================


To get the senders email address back.


.. code-block:: perl

     my $SenderEmail = $ParserObject->GetEmailAddress(
         Email => 'Juergen Weber <juergen.qeber@air.com>',
     );



GetRealname()
=============


to get the sender's \ ``RealName``\ .


.. code-block:: perl

     my $Realname = $ParserObject->GetRealname(
         Email => 'Juergen Weber <juergen.qeber@air.com>',
     );



SplitAddressLine()
==================


To get an array of email addresses of an To, Cc or Bcc line back.


.. code-block:: perl

     my @Addresses = $ParserObject->SplitAddressLine(
         Line => 'Juergen Weber <juergen.qeber@air.com>, me@example.com, hans@example.com (Hans Huber)',
     );


This returns an array with ('Juergen Weber <juergen.qeber@air.com>', 'me@example.com', 'hans@example.com (Hans Huber)').


GetContentType()
================


Returns the message body (or from the first attachment) "ContentType" header.


.. code-block:: perl

     my $ContentType = $ParserObject->GetContentType();
 
     (e. g. 'text/plain; charset="iso-8859-1"')



GetContentDisposition()
=======================


Returns the message body (or from the first attachment) "ContentDisposition" header.


.. code-block:: perl

     my $ContentDisposition = $ParserObject->GetContentDisposition();
 
     (e. g. 'Content-Disposition: attachment; filename="test-123"')



GetCharset()
============


Returns the message body (or from the first attachment) "charset".


.. code-block:: perl

     my $Charset = $ParserObject->GetCharset();
 
     (e. g. iso-8859-1, utf-8, ...)



GetReturnContentType()
======================


Returns the new message body (or from the first attachment) "ContentType" header
(maybe the message is converted to utf-8).


.. code-block:: perl

     my $ContentType = $ParserObject->GetReturnContentType();


(e. g. 'text/plain; charset="utf-8"')


GetReturnCharset()
==================


Returns the charset of the new message body "Charset"
(maybe the message is converted to utf-8).


.. code-block:: perl

     my $Charset = $ParserObject->GetReturnCharset();


(e. g. 'text/plain; charset="utf-8"')


GetMessageBody()
================


Returns the message body (or from the first attachment) from the email.


.. code-block:: perl

     my $Body = $ParserObject->GetMessageBody();



GetAttachments()
================


Returns an array of the email attachments.


.. code-block:: perl

     my @Attachments = $ParserObject->GetAttachments(
         UserType => 'Agent' # optional, but recommended
     );
     for my $Attachment (@Attachments) {
         print $Attachment->{Filename};
         print $Attachment->{Charset};
         print $Attachment->{MimeType};
         print $Attachment->{ContentType};
         print $Attachment->{Content};
 
         # optional
         print $Attachment->{ContentID};
         print $Attachment->{ContentAlternative};
         print $Attachment->{ContentMixed};
     }



GetReferences()
===============


To get an array of reference ids of the parsed email


.. code-block:: perl

     my @References = $ParserObject->GetReferences();


This returns an array with ('fasfda@host.de', '4124.2313.1231@host.com').


_DecodeString()
===============


Decode all encoded substrings.


.. code-block:: perl

     my $Result = $Self->_DecodeString(
         String => 'some text',
     );



_MailAddressParse()
===================



.. code-block:: perl

     my @Chunks = $ParserObject->_MailAddressParse(Email => $Email);


Wrapper for C<Mail::Address->parse($Email)>, but cache it, since it's
not too fast, and often called.