Detailed Description

Compose and send email activity

Overview

This API can be used to compose and send an email activity. Only one outbound email activity can be created and sent at a time.
If the setting "Enable secure messaging" is enabled, and the value of the setting "Types of emails agents are allowed to send" is "Only secure emails", the created activity will be a secure activity.

As part of completing this API request:

All macros present in the subject and content of the email activity will be expanded.

Since: 11.6.0.3

APIs

Method	URL	Description
POST	`/ws/v12/interaction/activity/send`	Compose and send 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:

User must have 'Create activity' action.
If "BCC" address is provided in request, the user must have "Edit BCC field" action.
The activity must be created in either the user's home department, or a department in which the user is a foreign user.
If one or more article type macros are present in the subject or content of the activity, the user must have 'View Folder' permission on the folder of these articles.
If one or more usage link macros are present in the subject or content of the activity, the user must have 'Execute' permission on these usage links.
If queue is provided:
- The user must have pull permissions on the queue.

Licenses

The logged in user must have the following licenses:

ECE MailPlus

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 non-inline attachments. 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 non-inline attachments of the activity. Each of these parts must contain following header:
  1. "Content-Disposition": This header must have a property by name "fileName", which indicates the file name of the attachment.
NOTE : Inline attachments are not supported by this API.

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 "compose".
payload.email.emailAddresses.to	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.to" will be added as a contact for the newly created customer. Refer to the description of the optional "customer" element for more details.
subject or attachments or content	Must have at least one of subject, attachments, or content.

Optional elements allowed in the request body

Name	Description
payload.email.emailAddresses.from	Must be provided if the setting "Enable secure messaging" is disabled. If provided: This specifies the email address of an active email alias in the application. The alias must be present in the department of the activity. Must be a single email address. This value will also be used as the reply-to email address. If not provided: The setting "Enable secure messaging" must be enabled in the department of the activity. The application will create a secure email using the "Secure Message Center" of the department of the activity.
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 to the case.
queue.name	The queue with which the created activity will be associated. Must be a queue in the department of the activity. The queue must be active. This is allowed only if the setting "Allow agent to associate a new outbound activity with a queue" is enabled in the department of the activity.
priority	Must be a value between 1 and 7.
dueDate	Must be a future date. Refer supported date format here.
subject	Must not exceed 245 characters. Subject can contain macros in the format (two grave accents followed by the macro name): ``<macro_name>. Eg: ``activity_id
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 4 - Compose an email for a new case with required elements and from email address, 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. Content can contain macros in the format (two grave accents followed by the macro name): ``<macro_name>. Eg: ``activity_id
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.bcc	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.
customer	This will be used to create a new customer only if a customer with the email address provided using "payload.email.emailAddresses.to" 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 cannot be more than the value of the partition setting "Maximum email size for dispatcher (MB)".
The email content size cannot be more than the value of the partition setting "Maximum body size for dispatcher (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 above for allowed content size.
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.
An empty or invalid macro name is present in the subject or content of the activity.
Unable to expand a macro present in the subject or content of the activity.

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 - Compose email with macros for an existing case with required elements, using XML/JSON as content-type
Example 2 - Compose email with macros for a new case with required elements, using Multipart/form-data as content-type
Example 3 - Compose an email with required elements, from email address and attachments, using XML/JSON as content-type
Example 4 - Compose an email for a new case with required elements and from email address, using Multipart/form-data as content-type
Example 5 - Composing an email for a new customer with all elements, using XML/JSON as content-type
Example 6 - Composing an email for a new customer with all elements, using Multipart/form-data as content-type