E-mail command

Import assets from defined e-mail addresses.

Overview

Customer e-mails can be stored in customer assets. New assets are created from e-mails that are read from a defined e-mail account and relations are created to all Person assets listed as recipients (for example send an e-mail to a customer and to the censhare Server). This e-mail is available as an asset with attachments to the customer asset. A PDF correction and annotation workflow with authors is possible. The PDF document can be sent to the authors. They then annotate the PDF with notes. The annotated PDF is sent back. The e-mail should be received, the asset found and the notes of the PDF document synchronized with the notes on the asset.

It is possible to receive user-generated content by e-mail. E-mails are received and new assets with attachments are created and assigned to a defined person.

censhare provides two mail service options:

Basic Mail Service
Modern Mail Service

Basic Mail Service

The basic mail service provides basic mail functionality by censhare. It supports IMAP/POP/POP3/SMTP with a basic authentication flow (username/password).

Modern Mail Service

The modern mail service OAuth 2.0 provides an external mail provider to handle basic mail operations for censhare users. The modern mail service has a more general structure to easily integrate with other mail service providers. According to Microsoft Exchange Online, Exchange Online will disable basic authentication for mail operations. Note that some censhare customers will be affected. We will support our customers in any circumstances. Currently, censhare supports modern mail services such as Microsoft Graph which supports modern authentication and also Exchange Online.

Configuration

 <account name="microsoft" store-protocol="graph" transport-protocol="smtp">
  <!--
  Additional properties may be set here.
  See http://java.sun.com/products/javamail/javadocs/index.html for a list of available properties.
    -->
  <property key="client.id" value="XXXXXXX"/>
  <property key="client.secret" value="XXXXXXXX"/>
  <property key="tenant.id" value="XXXXX"/>
  <property key="user.id" value="XXXXXX"/>
  <property key="mail.server" value="http://127.0.0.1:9500"/>
  <property key="mail.from" value="user mail"/>
 </account>

XML

Basic operations

Basic mail operations include send, list, receive and delete mail operations. Those operations are common for internal and external mail services.

Configuration

<account name="no-reply" store-protocol="pop3s" transport-protocol="smtp">
    <!--
    Additional properties may be set here.
    See http://java.sun.com/products/javamail/javadocs/index.html for a list of available properties.
      -->
    <property key="mail.from" value="censhare-Tracker <no-reply@censhare.com>"/>
    <property key="mail.pop3s.host" value="Outlook.office365.com"/>
    <property key="mail.pop3s.user" value="no-reply@censhare.com"/>
    <property key="mail.pop3s.password" value="XXXXX"/>
    <property key="mail.pop3s.connectiontimeout" value="5000"/>
    <property key="mail.pop3s.timeout" value="30000"/>
    <property key="mail.smtp.host" value="Smtp.office365.com"/>
    <property key="mail.smtp.port" value="587"/>
    <property key="mail.smtp.starttls.enable" value="true"/>
    <property key="mail.smtp.auth" value="true"/>
    <property key="mail.smtp.user" value="no-reply@censhare.com"/>
    <property key="mail.smtp.password" value="XXXXXX"/>
    <property key="mail.smtp.connectiontimeout" value="5000"/>
    <property key="mail.smtp.timeout" value="30000"/>
  </account>

XML

Attributes

<cs: command> attribute as “name”: “com.censhare.api.Mail.XXXX” specifies which command is used by the censhare mail service
<cs:param name="source"> attributes such as param name represent command parameter
<mails account-name="xxxxx"/> mails tag represent multi-mail tag with one mail account
- Define multi-mail tag between <mails></mails>
- Define specific folder name
- Define attribute as top to list top mails etc.
- Define the show-envelop attribute to show all message headers

Send e-mails

Single mail with an account

<cs:command name="com.censhare.api.mail.SendMail">
	<cs:param name="source">
		<mails account-name="mail-account">
			<mail
                sender-address="sender-mail-address"
                subject="Message of the day"
                >
				<recipient type="to" address="receiver-mail-address"/>
				<content mimetype="text/html" transfer-charset="UTF-8">hello from mail-account</content>
			</mail>
		</mails>
	</cs:param>
</cs:command>

XML

Single mail with multi-mails with an account

<cs:command name="com.censhare.api.mail.SendMail">
	<cs:param name="source">
		<mails account-name="mail-account">
			<mail
                sender-address="sender"
                subject="Message of the day"
                >
				<recipient type="to" address="receiver"/>
				<content mimetype="text/html" transfer-charset="UTF-8">hello from mail-account</content>
			</mail>
			<mail
                sender-address="sender"
                subject="Another Message of the day"
                >
				<recipient type="to" address="receiver"/>
				<multipart-body>
					<content mimetype="text/plain" transfer-charset="ISO-8859-1">Ciao</content>
				</multipart-body>
				<multipart-body
                  filename="link"
                  url="local file link / some internet url which is include pictures or pages etc"
                 />
			</mail>
		</mails>
	</cs:param>
</cs:command>

XML

Example

<cs:command name="com.censhare.api.mail.SendMail">
	<cs:param name="source">
		<mails account-name="mail-account">
			<mail
                sender-address="sender"
                subject="Another Message of the day"
                >
				<recipient type="to" address="receiver"/>
				<multipart-body>
					<content mimetype="text/plain" transfer-charset="ISO-8859-1">Ciao</content>
				</multipart-body>
				<multipart-body
                  filename="link"
                  url="censhare:///service/assets/asset/id/10000/version/2/element/actual/0/storage/text-preview/file/104403.xhtml"
                 />
			</mail>
		</mails>
	</cs:param>
</cs:command>

XML

Multi-mails with different accounts

<cs:command name="com.censhare.api.mail.SendMail">
	<cs:param name="source">
		<mails account-name="mail-account">
			<mail
                sender-address="sender"
                subject="Message of the day"
                >
				<recipient type="to" address="receiver"/>
				<content mimetype="text/html" transfer-charset="UTF-8">hello from mail-account</content>
			</mail>
		</mails>
		<mails account-name="another-account">
			<mail
                sender-address="sender"
                subject="Another Message of the day"
                >
				<recipient type="to" address="receiver"/>
				<content mimetype="text/html" transfer-charset="UTF-8">hello from another-account</content>
			</mail>
		</mails>
	</cs:param>
</cs:command>

XML

Result

List e-mails

List e-mails of a given account and folder

Attributes

folder - folder from which the mails will be returned
size - number of emails that are returned

Example

 <cs:command name="com.censhare.api.Mail.ListMail" returning=":resultVariable">
        <cs:param name="source">
          <mails account-name="account" folder="INBOX" size="1"/>
           <mails account-name="another-account" folder="INBOX" size="1"/>
        </cs:param>
 </cs:command>

XML

Result

<mails account-name="microsoft" folder="INBOX" size="3" xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions" timestamp="2022-04-20T14:08:43.817Z">
  <mail id="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQBGAAAAAADsPwiG4H63Q4lduK_Y8GM_BwDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAADPXkeUQomrRqSs2nj9ddhfAAAuQjoNAAA=" mime-msg-id="<eb19fc50-34b2-4077-8dc6-642e0d021252@FR2P281MB0789.DEUP281.PROD.OUTLOOK.COM>" uid="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQAuAAAAAADsPwiG4H63Q4lduK_Y8GM_AQDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAAA=" from-address="MicrosoftExchange329e71ec88ae4615bbc36ab6ce41109e@censhare87.onmicrosoft.com" subject="Undeliverable: Message of the day-3" sent-date="Tue Apr 19 15:12:38 CEST 2022">
    <recipient address="mko@censhare.com" type="to"/>
  </mail>
  <mail id="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQBGAAAAAADsPwiG4H63Q4lduK_Y8GM_BwDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAADPXkeUQomrRqSs2nj9ddhfAAAuQjoMAAA=" mime-msg-id="<1b862a2b-00aa-42a1-880f-ff0f49dd70ea@FR2P281MB0789.DEUP281.PROD.OUTLOOK.COM>" uid="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQAuAAAAAADsPwiG4H63Q4lduK_Y8GM_AQDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAAA=" from-address="MicrosoftExchange329e71ec88ae4615bbc36ab6ce41109e@censhare87.onmicrosoft.com" subject="Undeliverable: Message of the day-2" sent-date="Tue Apr 19 15:12:37 CEST 2022">
    <recipient address="mko@censhare.com" type="to"/>
  </mail>
  <mail id="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQBGAAAAAADsPwiG4H63Q4lduK_Y8GM_BwDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAADPXkeUQomrRqSs2nj9ddhfAAAuQjoLAAA=" mime-msg-id="<148774b4-9875-4330-aa18-11094858af06@FR2P281MB0789.DEUP281.PROD.OUTLOOK.COM>" uid="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQAuAAAAAADsPwiG4H63Q4lduK_Y8GM_AQDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAAA=" from-address="MicrosoftExchange329e71ec88ae4615bbc36ab6ce41109e@censhare87.onmicrosoft.com" subject="Undeliverable: Message of the day" sent-date="Tue Apr 19 15:12:37 CEST 2022">
    <recipient address="mko@censhare.com" type="to"/>
  </mail>
</mails>

XML

Read e-mail

Read e-mails of an account and IDs

Attributes

folder - the folder that will be read
show-envelop - show message headers
delete-after-reading - delete the e.mail after reading

<cs:command name="com.censhare.api.mail.ReadMail">
        <cs:param name="source">
         <mails account-name="mail-account" folder="INBOX" show-envelope="false">
               <mail id="XXXXX" delete-after-reading="false"/>
			   <mail id="XXXX" delete-after-reading="true"/> 
         </mails>
        </cs:param>
</cs:command>

XML

Result

<mails account-name="microsoft" folder="INBOX" show-envelope="false" xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions" from-address="Microsoft Outlook <MicrosoftExchange329e71ec88ae4615bbc36ab6ce41109e@censhare87.onmicrosoft.com>" replyto-address="Microsoft Outlook <MicrosoftExchange329e71ec88ae4615bbc36ab6ce41109e@.onmicrosoft.com>" subject="Undeliverable: Message of the day" sent-date="2022-04-19T13:12:38Z" content-type="multipart/report; report-type=delivery-status;
	boundary="b3f40379-7412-4c55-ac88-c036c8ef2c25"" timestamp="2022-04-20T14:15:57.828Z">
  <mail id="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQBGAAAAAADsPwiG4H63Q4lduK_Y8GM_BwDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAADPXkeUQomrRqSs2nj9ddhfAAAuQjoNAAA=" delete-after-reading="false"/>
  <recipient address="sender" type="to"/>
  <content type="text/plain; charset="us-ascii"">Delivery has failed to these recipients or groups:

receiver<mailto:receiver>
Your message wasn't delivered because the recipient's email provider rejected it.

....

Original message headers:

Received: from FR2P281MB0789.DEUP281.PROD.OUTLOOK.COM
 ([fe80::d1f:d8cc:a2e3:f126]) by FR2P281MB0789.DEUP281.PROD.OUTLOOK.COM
 ([fe80::d1f:d8cc:a2e3:f126%3]) with mapi id 15.20.5186.013; Tue, 19 Apr 2022
 13:12:38 +0000
MIME-Version: 1.0
Content-Type: text/plain
Date: Tue, 19 Apr 2022 13:12:38 +0000
Message-ID:
        <FR2P281MB078967A4772883E33D41B4AE9DF29@FR2P281MB0789.DEUP281.PROD.OUTLOOK.COM>
Subject: Message of the day-3

</content>
  <content type="text/html; charset="us-ascii""><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"></head><body>
<p><b><font color="#000066" size="3" face="Arial">Delivery has failed to these recipients or groups:</font></b></p>
<font color="#000000" size="2" face="Tahoma"><p><a href="mailto:mko@censhare.com">mko@censhare.com</a><br>
</font>
<font color="#000000" size="3" face="Arial">Your message wasn't delivered because the recipient's email provider rejected it.<br>
</font>
<font color="#000000" size="2" face="Tahoma"><br>

XML

Delete e-mail

Attributes

folder - folder from which e-mails are deleted
id - e-mail ID

Example

 <cs:command name="com.censhare.api.mail.DeleteMail">
        <cs:param name="source">
         <mails account-name="microsoft" folder="INBOX">
         <mail id="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQBGAAAAAADsPwiG4H63Q4lduK_Y8GM_BwDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAADPXkeUQomrRqSs2nj9ddhfAAAuQjoNAAA="/>
         </mails>
        </cs:param>
</cs:command>

XML

Result

<mails account-name="microsoft" folder="INBOX" xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions" timestamp="2022-04-20T14:21:34.732Z">
  <mail id="AAMkADRkNDM1Y2IxLWY1MWYtNDAwNy1hMDU1LWQzODU5ZWViNzAyZQBGAAAAAADsPwiG4H63Q4lduK_Y8GM_BwDPXkeUQomrRqSs2nj9ddhfAAAAAAEMAADPXkeUQomrRqSs2nj9ddhfAAAuQjoNAAA="/>
</mails>

XML