MailOperator (Punch Punch Language Runtime Library 6.4.4 API)

java.lang.Object
- org.thales.punch.libraries.punchlang.operator.MailOperator

public class MailOperator
extends Object

The Mail Operator parses email headers and content from a Tuple.

It can also perform simple operations on email addresses.

Operations on an Email Tuple

Here is the email used for following examples :


 Received: from mx1.ovh.net (unknown [10.110.115.173])
 Received: from localhost (HELO queueout) (127.0.0.1)
 Date: Wed, 30 Sep 2020 14:30:22 +0200
 From: Sender Identity <sender.account@sender.domain.com>
 Reply-to: sender.account@sender.domain.com
 To: Receiver1 Identity <receiver1.account@receiver1.domain.com>, receiver2@gmail.com
 Subject: Testing
 MIME-Version: 1.0
 Content-Type: MULTIPART/MIXED; BOUNDARY="277887299-1503234992-1068806039"

    This message is in MIME format. The first part should be readable text.

 --277887299-1503234992-1068806039
 Content-Type: TEXT/PLAIN; charset=UTF-8

 This is a plain text message.
 --277887299-1503234992-1068806039
 Content-Type: TEXT/HTML: charset=UTF-8

 <html><body>
     This is a html text message.
 </body></html>

 --277887299-1503234992-1068806039
 Content-Type: IMAGE/jpeg; name="picture.jpg"
 Content-Transfer-Encoding: BASE64
 Content-Disposition: attachment; filename="picture.jpg"

 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja3kAAQAEAAAAPAAA/+4ADkFk
 b2JlAGTAAAAAAf/bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAoKCwoKDBAM
 *******some lines have been deleted for clarity******
 SBPHq9oFkl6gJoASCLUQVKQE0AkCaAKASBPUBNUBJQIJKJQBgK8SCavpAmvD
 vAmoCrAmvUA1ANQB9PAoVIFeJR//2Q==

 --277887299-1503234992-1068806039
 Content-Type: TEXT/plain; charset=US-ASCII; name="report.txt"
 Content-Transfer-Encoding: BASE64
 Content-Disposition: attachment; filename="report.txt"

 ZWNlIDogIDE0NC4xNi42NC40IDogICAgMzEyOA0Kc2VyYzogIDE0NC4xNi43
 OS41ODoJMzEyOCAgIG9ubHkgYWZ0ZXIgNiBpbiB0aGUgZXZlbmluZyB0byA5
 IGluIG1vcm5pbmcNCmNzYSA6ICAxNDQuMTYuNjcuOCA6CTgwODANCg==

 --277887299-1503234992-1068806039--

Parsing headers

The MailOperator can parse email headers defined in RFC 822.

Suppose you have the following Tuple from an SMTP Input with the email from above :


  {
   "emails": {
     "log": "Date: Wed, 30 Sep 2020 14:30:22 +0200\r\nFrom: Sender Identity <sender.account@sender.domain.com>\r\nFrom:...."
     }
  }

The following punchlet code will extract the email headers values :


     Tuple email = root:[emails][log];
     Tuple result;
     mail().on(email).
           .getHeader("To")
           .getHeader("From")
           .getHeader("RePlY-tO") // header names are case insensitive
           .getHeader("Subject")
           .getHeader("Date")
           .getHeader("Absent-Header") // Nonexistent headers are ignored
           .into(result);
     print(result);

Result :


     {
       "to": "Receiver1 Identity <receiver1.account@receiver1.domain.com>, receiver2@gmail.com"
       "from": "Sender Identity <sender.account@sender.domain.com>",
       "reply-to": "sender.account@sender.domain.com",
       "subject": "Testing",
       "sent-date": "2020-09-30T14:30:22.000Z",
     }

It is also possible to parse multiple headers at once :


     mail().on(email)
           .getAllHeaders()
           .into(result);

     mail().on(email)
           .getHeaders("to","from","MIME-version")
           .into(result);

     mail().on(email)
           .getAllHeadersExcept("Content-Type", "to", "from", "received")
           .into(result);

Note on duplicate headers.

Some headers can be duplicated in an email. This often happens for 'Received' and some 'X-' headers.

By default, the MailOperator only gets the last matching value for a header.

If you need all the values for a header, you can use

getHeaderAsList("Received");

This will put all values for the header in a list.

Parsing Content

Mail Operator can parse content from a MIME Multipart message. It will recursively parse and decode the MIME parts of your email.

Depending on the `Content-Type` header of the MIME part, its content can be retrieved with :

getPlainContent() : get content for `Content-Type: text/plain`.
getHtmlContent() : get content for `Content-Type: text/html`.

The MIME parts with other `Content-Type` are considered as attachments.

The following punchlet code will extract the email headers and email content :


     mail().on(email).
           .getContentSize()
           .getPlainContent()
           .getHtmlContent()
           .into(result);

Produces


      {
        "content-size": 1162,
        "plain-content": "This is a plain text content.",
        "html-content": "<html><body>This is a html text content.</body></html>"
      }

Parsing Attachments

The MailOperator can be used to retrieve information and data about email attachments.

You can choose to get email attachment data or not. The data is encoded in base64 using the MIME type base64 encoding scheme. See Base64.getMimeDecoder() to decode it.


     mail.on(email)
         .getNbAttachments()
         .getAttachmentsWithoutData() // get only attachment info 
         .getAttachmentsWithData()  // get attachment info and encoded data 
         .into(result);

Produces :


     {
         "nb-attachments" : 2,
         "attachments": [
              {
                  "size": 102983,
                  "name": "picture.jpg",
                  "content-type": "IMAGE/jpeg",
                  "data": "/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja3kAAQAEAAAAPAAA/+4ADkFk\nb2JlAGTAAAAAAf/bAIQABg..."
              },
              {
                  "size": 833,
                  "name": "report.txt",
                  "content-type": "TEXT/plain",
                  "data": "ZWNlIDogIDE0NC4xNi42NC40IDogICAgMzEyOA0Kc2VyYzogIDE0NC4xNi43\nOS41ODoJMzEyOCAgIG9ub..."
              }
         ]
     }

Operations on an Email Address

MailOperator can perform simple operations on an email address string. Those methods can be called directly from the class.


     MailOperator.isValidEmailAddress("John Doe <john.doe@domain.com>"); // true
     MailOperator.parseEmailAddress("John Doe <john.doe@domain.com>"); // "john.doe@domain.com"
     MailOperator.parseEmailAddressDomain("John Doe <john.doe@domain.com>"); // "domain.com"
     MailOperator.parseEmailAddressAccount("John Doe <john.doe@domain.com>"); // "john.doe"

Constructor Summary

Constructors
Constructor and Description

MailOperator()
Create a MailOperator.

Constructors
Constructor and Description
`MailOperator()` Create a MailOperator.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`MailOperator`	`getAllHeaders()` Get all headers names and values in the email.
`MailOperator`	`getAllHeadersExcept(String... headerNames)` Get all headers names and values in the email except the ones supplied in the list.
`MailOperator`	`getAttachmentsWithData()` Get list of attachments with their data.
`MailOperator`	`getAttachmentsWithoutData()` Get list of attachments without their data.
`MailOperator`	`getContentSize()` Get size of the email content (headers not included).
`MailOperator`	`getHeader(String headerName)` Get header value if it is in the email.
`MailOperator`	`getHeaderAsList(String headerName)` Get header value if it is in the email.
`MailOperator`	`getHeaders(String... headerNames)` Get headers names and values in the email based on provided list of header names.
`MailOperator`	`getHtmlContent()` Get text/html content in an email object after parsing MIME content.
`MailOperator`	`getNbAttachments()` Get number of attachments in the email.
`MailOperator`	`getPlainContent()` Get text/plain content in an email object after parsing MIME content.
`boolean`	`hasHeader(String headerName)` Check if the header is in the email.
`boolean`	`into(Tuple tuple)` Put parsed headers and content into tuple.
`MailOperator`	`isMultipart()` Check if email content is in multiple MIME parts.
`static boolean`	`isValidEmailAddress(String email)` Check if email address is valid according to syntax rules of RFC 822.
`MailOperator`	`on(String email)` Make the operator work on an input String.
`MailOperator`	`on(Tuple input)` Make the operator work on an input Tuple.
`static String`	`parseEmailAddress(String emailAddr)` Parse email address as it might be in the following formats: "From" : john.doe@domain.com "From" : John Doe "From" : david.lynch@mit.edu Return null if the email address is not valid.
`static String`	`parseEmailAddressAccount(String emailAddr)` Parse email address account after checking if the email address is valid.
`static String`	`parseEmailAddressDomain(String emailAddr)` Parse email address domain after checking if the email address is valid.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MailOperator
```
public MailOperator()
```
    Create a MailOperator.
- Method Detail
  - on
```
public MailOperator on(Tuple input)
```
    Make the operator work on an input Tuple. The Tuple must contain a String leaf value.
    
    Parameters:
    
    input - Tuple with email as leaf value.
    
    Returns:
    
    this MailOperator
  - on
```
public MailOperator on(String email)
```
    Make the operator work on an input String.
    It will build a MimeParser from a MimeMessage. It will build new Tuple to store results.
    
    Parameters:
    
    email - email in string
    
    Returns:
    
    this MailOperator
  - hasHeader
```
public boolean hasHeader(String headerName)
```
    Check if the header is in the email.
    
    Parameters:
    
    headerName - header name. Case insensitive.
    
    Returns:
    
    if header is in the email.
  - getHeader
```
public MailOperator getHeader(String headerName)
```
    Get header value if it is in the email. Will return only last header value in case of duplicate header name.
    
    Parameters:
    
    headerName - header name. Case insensitive.
    
    Returns:
    
    this MailOperator
  - getHeaderAsList
```
public MailOperator getHeaderAsList(String headerName)
```
    Get header value if it is in the email. Will return list of values in case of duplicate header name.
    
    Parameters:
    
    headerName - header name. Case insensitive.
    
    Returns:
    
    this MailOperator
  - getAllHeaders
```
public MailOperator getAllHeaders()
```
    Get all headers names and values in the email.
    
    Returns:
    
    MailOperator
  - getHeaders
```
public MailOperator getHeaders(String... headerNames)
```
    Get headers names and values in the email based on provided list of header names.
    
    Parameters:
    
    headerNames - list of headers to retrieve
    
    Returns:
    
    this MailOperator
  - getAllHeadersExcept
```
public MailOperator getAllHeadersExcept(String... headerNames)
```
    Get all headers names and values in the email except the ones supplied in the list.
    
    Parameters:
    
    headerNames - list of headers to exclude
    
    Returns:
    
    this MailOperator
  - getContentSize
```
public MailOperator getContentSize()
```
    Get size of the email content (headers not included).
    
    Returns:
    
    this MailOperator
  - getPlainContent
```
public MailOperator getPlainContent()
```
    Get text/plain content in an email object after parsing MIME content.
    
    Returns:
    
    this MailOperator
  - getHtmlContent
```
public MailOperator getHtmlContent()
```
    Get text/html content in an email object after parsing MIME content.
    
    Returns:
    
    this MailOperator
  - getNbAttachments
```
public MailOperator getNbAttachments()
```
    Get number of attachments in the email.
    Every MIME part with Content-Type other than 'text/plain' or 'text/html' will be considered as attachment.
    
    Returns:
    
    this MailOperator
  - getAttachmentsWithoutData
```
public MailOperator getAttachmentsWithoutData()
```
    Get list of attachments without their data. Provide content-type, name, size.
    
    Returns:
    
    this MailOperator
  - getAttachmentsWithData
```
public MailOperator getAttachmentsWithData()
```
    Get list of attachments with their data. Provide content-type, name, size and data. Data is encoded using the MIME type base64 encoding scheme.
    
    Returns:
    
    this MailOperator
  - isMultipart
```
public MailOperator isMultipart()
```
    Check if email content is in multiple MIME parts.
    
    Returns:
    
    this MailOperator
  - into
```
public boolean into(Tuple tuple)
```
    Put parsed headers and content into tuple.
    
    Parameters:
    
    tuple - tuple to put parsed results
    
    Returns:
    
    true if some key-value was extracted.
  - isValidEmailAddress
```
public static boolean isValidEmailAddress(String email)
```
    Check if email address is valid according to syntax rules of RFC 822.
    
    Returns:
    
    if email is valid
  - parseEmailAddress
```
public static String parseEmailAddress(String emailAddr)
```
    Parse email address as it might be in the following formats: "From" : john.doe@domain.com "From" : John Doe "From" : david.lynch@mit.edu Return null if the email address is not valid.
    
    Parameters:
    
    emailAddr - email to parse
    
    Returns:
    
    parsed email address
  - parseEmailAddressDomain
```
public static String parseEmailAddressDomain(String emailAddr)
```
    Parse email address domain after checking if the email address is valid. Return null if the email is not valid.
    
    Parameters:
    
    emailAddr - email to parse domain
    
    Returns:
    
    email address domain
  - parseEmailAddressAccount
```
public static String parseEmailAddressAccount(String emailAddr)
```
    Parse email address account after checking if the email address is valid. Return null if the email is not valid.
    
    Parameters:
    
    emailAddr - email to parse account
    
    Returns:
    
    email address account

Class MailOperator

Operations on an Email Tuple

Parsing headers

Parsing Content

Parsing Attachments

Operations on an Email Address

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MailOperator

Method Detail

on

on

hasHeader

getHeader

getHeaderAsList

getAllHeaders

getHeaders

getAllHeadersExcept

getContentSize

getPlainContent

getHtmlContent

getNbAttachments

getAttachmentsWithoutData

getAttachmentsWithData

isMultipart

into

isValidEmailAddress

parseEmailAddress

parseEmailAddressDomain

parseEmailAddressAccount