Detailed Description

Create Incoming Email Activity

Overview

This API can be used to create a new incoming email activity. Only one email activity can be created at a time.

Since

14.0.3

APIs

Method	URL	Description
POST	`/ws/v12/interaction/activity`	Create incoming email activity.

Authentication

Authentication is required. The client must be logged in to call this API. Each API request must contain X-egain-session request header returned by Login API.

Permissions

All of the following are required:

The user must have administer partition permission.

Licenses

The following licenses must be installed:

Any User Licenses

Request

Request headers

Name	Description	Allowed values	Default value
X-egain-session	Session ID obtained from Login API response header	N/A	N/A
Content-Type	Media type sent by the client.	`application/xml` or `application/json` or `multipart/form-data`	N/A
Accept	Content type accepted by the client.	`application/xml` or `application/json`	N/A
Accept-Language	Language locale accepted by client (used for locale specific fields in resource representation and in error responses)	Supported 'Accept-Language' header codes	`default system language`

Request Body

The request body is mandatory. The request body can be in one of the below two formats:

XML / JSON representing the activity.
- The activity can contain attachments which can be either inline or non-inline. Refer the attachments Element section for more details.

Multipart form data.
- The following two parts must be present:
  1. "data": This part must have the data representing the email activity. This can either be in XML format or JSON format.
  2. "data-type": This part identifies the data type of "data" part. It can have one of the two values - "application/json" or "application/xml".
- Optionally there can be more parts that represent attachments of the activity. Each of these parts must contain one of the following headers:
  1. "Content-ID": Presence of Content-ID header implies that this is an inline attachment and the header contains the identifier for the attachment. This may additionally have a header by name "Content-Disposition", with "fileName" as a property.
  a) The value of Content-ID must be enclosed within angular brackets (between '<' and '>'). For example, Content-ID: <image.nosp@m.001..nosp@m.png@0.nosp@m.1D08.nosp@m.8BF.E.nosp@m.1D8D.nosp@m.780>.
  2. "Content-Disposition": "Content-Disposition" implies that this is a non-inline attachment. This must have a property by name "fileName" - This property contains the file name of the attachment.
  Note : If both Content-ID and Content-Disposition headers are present, the attachment will be treated as an inline attachment.

Note about inline attachments:

Inline attachments are supported using the cid URL scheme. The cid URL scheme allows references to attachments from the email content. Refer Example 3 - Create an inbound email with inline and non-inline attachments, using XML/JSON as content-type and Example 4 - Create inbound email with inline and non-inline attachments, using Multipart/form-data as content-type for details.

Elements required in the request body

Name	Description
department.name	Name of the department in which the activity should be created.
type.value	Must be "email".
type.subtype.value	Must be "general".
payload.email.emailAddresses.from	Specifies the customer's email address. This must be a single email address. If "Customer departmentalization" setting is enabled, this API will try to find the customer in the department of the activity, otherwise it will try to find the customer across the application. If a customer with this email address does not exist: The details of the customer to be created must be provided using the customer element. This will be used to create a new customer in the application The email address specified in "payload.email.emailAddresses.from" will be added as a contact for the newly created customer. Refer to the description of the optional "customer" element for more details.
payload.email.emailAddresses.receiver	Specifies the email address of an active email alias in application. The email activity is associated with this email alias. Must be a single email address. This email address must match an active alias in the specified department.
payload.email.date	Date when email was sent. Refer supported date format here.
subject or attachments or content	Must have atleast one of subject, attachments or content.

Optional elements allowed in the request body

Name	Description
case.id	If case.id is not provided, the application will create a new case for the activity. If provided, this case must exist in the system and the activity will be associated with the case.
isSecure	Flag to indicate whether the activity is a secure activity or not. Must be "true" or "false". If "true", the created activity will be a secure email. Default value is "false". If "Enable secure messaging" setting is disabled in the application, the customer cannot create a secure email and will recieve 400 error response code.
subject	Must not exceed 255 characters.
attachments	If attachments are provided, file type of any attachment must not be blocked in the application. This element is not allowed for multipart/form-data requests. To send attachments for multipart/form-data requests, refer Example 6 - Create an inbound email by specifying all attributes, using Multipart/form-data as content-type.
customAttributes	Name must match one of the custom attributes configured in application. If the custom attribute is configured as an enumeration, the value must be one of the predefined values. For string type of custom attribute that is not configured as an enumeration, refer list of Allowed Characters For Custom Attributes.
payload.email.contents	Supported content types are "text" and "html". One or both can be provided.
payload.email.emailAddresses.to	All addresses must be in the valid email address format. Must not exceed 255 characters. Refer email address definition for the valid email address format.
payload.email.emailAddresses.cc	All addresses must be in the valid email address format. Must not exceed 255 characters. Refer email address definition for the valid email address format.
payload.email.emailAddresses.replyTo	If present, any replies for this email will be sent to this email address. Must be a single email address in the valid email address format. Must not exceed 255 characters. Refer email address definition.
customer	This will be used to create a new customer only if a customer with the email address provided using "payload.email.emailAddresses.from" attribute does not exist in the application. Otherwise, this attribute is ignored. This API does not allow specifying "department.name" attribute in the customer element. Instead, when creating a new customer, customer's department is determined as follows: If the "Customer departmentalization" setting is enabled, the customer will be created in the department of the activity. If the "Customer departmentalization" setting is not enabled, the created customer will be shared across all departments Refer the "Customer creation" API for more details about the customer element.

Size restrictions

The email size (includes email content and attachments) cannot be more than the value of the partition setting "Maximum email size for retriever (MB)".
The email content size cannot be more than the value of the partition setting "Maximum body size for retriever (KB)".

attachments Element

Each attachment must be present within a separate attachment element. It must have the following representation:

Elements required for attachment

Name	Description
contentType	content type of the attachment content. Must not exceed 255 characters.
content	content of the attachment in base64 encoded format. Refer Size restrictions section for allowed content size.

Optional elements allowed for attachment

Name	Description
isInline	Flag to indicate if this is an inline attachment or not. Must be set to true for inline attachments.
contentId	This represents the identifier for the attachment. This is required only for inline attachments.
fileName	Name of the attachment file. Must not exceed 255 characters.

Supported API specific query parameters

None

Supported common query parameters

None

Response

Response headers

Name	Description	Possible values
X-egain-session	Session ID of the current user session	N/A
Content-Type	Media type of response body	`application/xml` or `application/json`
Location	Location of the new created activity	N/A

Request body XML schemas:

schema-interaction-activity-Activity

Response body XML schemas:

schema-kb-WSError - used in case of error

HTTP status codes

Success Status codes

201 - Created

The request was successfully executed

Failure Status codes

400 - Bad Request

Any query parameter is sent in the request.
Request body does not contain the required elements.
An unsupported element is present in the request body.
Elements provided do not adhere to the rules stated in the Request section.
Request body is empty.
Size restrictions are violated. Refer Size restrictions section for details.

401 - Unauthorized

X-egain-session request header is missing
Session is invalid or expired

403 - Forbidden

The user does not have sufficient permissions. Refer the Permissions section for details.

406 - Not Acceptable

If invalid language header is provided.

500 - Internal server error

Examples:

Example 1 - Create secure email for an existing case with required elements, using XML/JSON as content-type
Example 2 - Create email for a new case with required elements, using Multipart/form-data as content-type
Example 3 - Create an inbound email with inline and non-inline attachments, using XML/JSON as content-type
Example 4 - Create inbound email with inline and non-inline attachments, using Multipart/form-data as content-type
Example 5 - Create a secure inbound email by specifying all attributes, using XML/JSON as content-type
Example 6 - Create an inbound email by specifying all attributes, using Multipart/form-data as content-type