Create incoming email activity

Overview

Use this API to create a new incoming email activity. Users can only create one activity at a time.

Note:

  • If actor is customer, then created incoming email activity is always secure.

    Permissions

    Actor Permission
    User Must have 'Manage partition resources' privilege.
    Client Application No additional permission required.
    Customer
  • All authenticated customers can access this API.
  • If the query parameter customer={id} is provided, the logged in customer must be authorized to perform this action on behalf of the customer specified through the "customer" query parameter. Otherwise, the application returns a 400 (bad request). Refer Customer grants for more information about authorization
    		•
SecurityoAuthUser or oAuthClient or oAuthCustomer
Request
query Parameters
customer
string
Actor Description
User / Client Application Not allowed.
Customer
  • The customer must be authorized to perform this action on behalf of the customer specified through the "customer" query parameter.
  • The activity is created for the customer specified through this query parameter. If this parameter is not provided, the activity is created for self (logged in customer).
Examples:
customer=
customer=1000
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

Actor Name Description
User / Client Application department.name Name of the department in which the activity should be created.
User / Client Application 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 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.from" is added as a contact for the newly created customer.
  • Refer to the description of the optional "customer" element for more details.
Customer payload.email.messageCenter.id Specifies an active message center in the application. If customer departmentalization setting is enabled, the message center must be in the same department as the customer.
User / Client Application / Customer type.value Type of the activity. Must be "email".
User / Client Application / Customer type.subtype.value Subtype of the activity. Must be "general".
User / Client Application / Customer subject or attachments or content Must have at least one of subject, attachments or content.
User / Client Application / Customer 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. If actor is customer and customer departmentalization setting is enabled, the alias must be in the same department as the customer.

Note: For customer, one of payload.email.emailAddresses.receiver or payload.email.messageCenter.id must be provided. The department of the activity is derived based on the value of payload.email.emailAddresses.receiver or payload.email.messageCenter.id.

Optional elements allowed in the request body

| User / Client Application | secure | Flag to indicate whether the activity is a secure activity or not. Must be "true" or "false". If "true", the created activity is 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 receives 400 error response code.| | User / Client Application | payload.email.emailAddresses.to   | All addresses must be in the valid email address format.| | User / Client Application | payload.email.emailAddresses.cc   | All addresses must be in the valid email address format.| | User / Client Application | customer | This is 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 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.| | Customer | payload.email.emailAddresses.from | Specifies the sender's email address.
If this attribute is not provided, the application automatically figures out the email address to use for the activity.
If provided, must be a single email address.
  1. If the query parameter "customer" is not provided:
    • If this email address is present in the application, it must be associated with the logged in contact. If the email address is not present in the application, a new contact point with the provided email address is created and used for activity creation.
    • If "Customer departmentalization" setting is enabled in the application, this email address is looked up in the department of the customer.
  2. If the query parameter "customer" is provided, this attribute ("payload.email.emailAddresses.from") must not be provided. The application automatically figures out the email address to use for the activity, since the activity is being created for a different customer.
    • If the application does not find any email addresses for the customer provided through "customer" query parameter, the application errors out. It does not create a new email address for the customer.
| | Customer | issueType.id | ID of the issue type of the activity. This can be provided only when payload.email.messageCenter.id is provided. The issue type must be associated with the message center specified through payload.email.messageCenter.id.| | User / Client Application / Customer | case.id | If provided, this case must exist in the system and the activity is associated with the case. If case.id is not provided, the application creates a new case for the activity.| | User / Client Application / Customer | subject | Email activity subject| | User / Client Application / Customer | attachments | Attachments of the email activity. Refer 'Attachments' section for more details. | | User / Client Application / Customer | 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.| | User / Client Application / Customer | payload.email.content | Supported content types are "text" and "html". One or both can be provided.| | User / Client Application / Customer | payload.email.emailAddresses.replyTo   | If present, any replies for this email is sent to this email address. Must be a single email address in the valid email address format.| | User / Client Application / Customer | payload.email.date | Date when email was sent. If this attribute is not sent, email is created with current date.|

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.

Optional elements allowed for attachment

Name Description
inline 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.

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.

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/general
Request samples
application/json
  • PATCH /core/casemgr/v3/activity/email/general
  • This example demonstrates the following:
    • Create incoming email activity with required attributes.
{
  • "department": {
    },
  • "type": {
    },
  • "subject": "laptop issue",
  • "payload": {
    }
}
Response samples
application/json
{
  • "code": "400-101",
  • "developerMessage": "Unsupported query parameter(s) supplied: '<query_parameter>'."
}