Compose email activity

Overview

Use this API to compose and save or send or send-complete an email activity. Only one outbound email activity can be created 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 is a secure activity.
For 'send' and 'sendcomplete' action type, as part of completing this API request:

  • All macros present in the subject and content of the email activity is expanded.

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:

  • eGain Advisor Desktop or eGain MailPlus

SecurityoAuthUser
Request
path Parameters
actionType
required
string

Action type for newly created email activity as below:

  • save: To compose and save an email activity.
  • send: To compose and send an email activity.
  • sendcomplete: To compose and send-complete an email activity.
Enum: "save" "send" "sendcomplete"
query Parameters
expandMacros
string

This is required to expand macros in the content and subject of the email. If the content or subject contains macros and this query parameter is not passed, the macros remains unexpanded.
Note: This is only applicable for 'save' action type.

Value: "yes"
header Parameters
Accept-Language
required
string
Default: en-US

Language locale accepted by client (used for locale specific fields in resource representation and in error responses).

Enum: "en-US" "es-ES" "fr-FR" "it-IT" "de-DE" "nl-NL" "pt-BR" "pt-PT" "da-DK" "ru-RU" "fr-CA" "zh-CN" "ja-JP" "ko-KR" "sv-SE"
Accept
required
string
Default: application/json

Content type accepted by client.

Enum: "application/json" "application/xml"
Content-Type
required
string
Default: application/json

Media type sent by the client.

Enum: "application/json" "application/xml" "application/x-www-form-urlencoded" "multipart/form-data" "text/plain"
Request Body schema: application/json

The request body is mandatory. Request body can be in either XML or JSON format.

Elements required in request body

Name Description
department.name Name of the department in which the activity should be created.
type.value Type of the activity. Must be "email".
type.subtype.value Subtype of the activity. 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 tries to find the customer in the department of the activity, otherwise it tries 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 is used to create a new customer in the application
  • The email address specified in "payload.email.emailAddresses.to" is 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 is also 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 creates a secure email using the "Secure Message Center" of the department of the activity.
case.id If case.id is not provided, the application creates a new case for the activity. If provided, this case must exist in the system and the activity is associated to the case.
queue.name The queue with which the created activity is associated. Must be a queue in the department of the activity.
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 Priority of the email activity.
dueDate Due date of email activity. Must be a future date.
subject Subject of email activity
Subject can contain macros in the format (two grave accents followed by the macro name): ``. Eg: ``activity_id
attachments Attachments of the email activity. Refer 'Attachments' section for more details.
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.
payload.email.content 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): ``. Eg: ``activity_id
payload.email.emailAddresses.cc   All addresses must be in the valid email address format.
payload.email.emailAddresses.bcc   All addresses must be in the valid email address format.
customer This is 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 is created in the department of the activity.
  • If the "Customer departmentalization" setting is not enabled, the created customer is 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
altId Alternate ID of the attachment.
Array of objects (link) >= 0 items

Link to the current activity.

object (_case)

Brief information about the cases of the activity.

object (department)

Department of the activity.

object (mode)

Mode of the activity.

object (type)

Type of the activity.

secure
boolean (secure)

Indicates whether the activity is secure or not.

sentOnBehalf
boolean (sentOnBehalf)

Indicates whether the activity was created by a customer on behalf of another customer.

object (status)

Status of the activity.

priority
string (priority)

Indicates the priority of the activity.

Enum: "1" "2" "3" "4" "5" "6" "7"
created
string <date-time> (created)

Date of creation of the activity.

object (created)

Activity creation details (user info).

lastModified
string <date-time> (lastModified)

Date of modification of the activity.

object (lastModifiedBy)

Details of the last modification of the activity (user info).

dueDate
string <date-time> (dueDate)

Due date of this activity.

subject
string (subject) <= 255 characters

Subject of this activity.

object (language)

Language of the activity.

object (userLastWorked)

User who last worked on this activity.

object (customer)

Customer of this activity.

object (classifications)

Classifications of the activity.

object (queue)

Queue associated with this activity.

object (attachments)

Attachments of this activity.

object (notes)

Notes of this activity.

contactPointData
string (contactPointData)

Contains the contact point information.

object (lastDepartment)

Information about the previous department of this activity.

object (issueType)

Issue type of the activity.

contentPurged
boolean (contentPurged)

Indicates whether the activity content is purged.

object (payload)

Payload of the activity.

object (customAttributes)

Custom attributes of the activity.

object (virtualAssistant)

Virtual assistant information.

object (channel)

Channel for the activity.

id
string (id)

Id of the activity.

Responses
201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

406

Not Acceptable

500

Internal server error

post/activity/email/compose/{actionType}
Request samples
application/json
  • POST /core/casemgr/v3/activity/email/compose/save
  • This example demonstrates the following:
    • Composing an email for an existing case
    • Composing an email using required elements, subject and content.
    • Using macros in subject and content of the email.
    • Note that since "from email address" is not provided, this will create a secure email.
{
  • "department": {
    },
  • "type": {
    },
  • "case": {
    },
  • "subject": "Issue with mobile phone. Ref: ``external_case_id",
  • "payload": {
    }
}
Response samples
application/json
{
  • "code": "400-101",
  • "developerMessage": "Unsupported query parameter(s) supplied: '<query_parameter>'."
}