How to Send an Email to a Client on Behalf of an Employee
Scope:
crmWho can perform the method: users with permission to modify a CRM entity
An email can be sent automatically through the CRM. The "From" field will display the name and email address of the employee. An event for the outgoing email will be added to the contact's card.
To send the email, we will sequentially execute three methods:
-
crm.contact.get — retrieve the client's data
-
user.get — retrieve the employee's data
-
crm.activity.add — create an activity of type "Email"
1. Retrieve Client Data
We will use the method crm.contact.get with the client's identifier. The identifier value can be stored in the variable contactID. For example, we will retrieve the contact data with the identifier 1.
How to Use Examples in Documentation
let contactID = 1;
BX24.callMethod(
'crm.contact.get',
{ 'id': contactID },
function(result) {
if (result.error()) {
reject(result.error());
} else {
resolve(result.data());
}
}
);
$contactID = 1;
$resultContact = CRest::call(
'crm.contact.get',
[
'id' => $contactID
]
);
As a result, we will obtain the client's data, including the email address EMAIL and the identifier of the responsible employee ASSIGNED_BY_ID.
{
"result": {
"ID": "1",
"NAME": "Alex",
"SECOND_NAME": "Kirillovich",
"LAST_NAME": "Vronsky",
"ASSIGNED_BY_ID": "61",
"EMAIL": [
{
"ID": "1328",
"VALUE_TYPE": "WORK",
"VALUE": "vronsky@example.com",
"TYPE_ID": "EMAIL"
}
]
}
}
2. Retrieve Employee Data
To get the data of the responsible employee, we will use the method user.get with a filter by the employee's identifier. The identifier should take the value from the ASSIGNED_BY_ID field of the resultContact object.
BX24.callMethod(
'user.get',
{
'filter': {
'ID': resultContact.ASSIGNED_BY_ID
}
},
function(result) {
if (result.error()) {
reject(result.error());
} else {
resolve(result.data());
}
}
);
{
$resultUser = CRest::call(
'user.get',
[
'filter' => [
'ID' => $resultContact['result']['ASSIGNED_BY_ID']
]
]
);
}
We will obtain the employee's data, including the email address EMAIL.
{
"result": [
{
"ID": "61",
"ACTIVE": true,
"NAME": "John",
"LAST_NAME": "Peterson",
"EMAIL": "johnpeterson@example.com"
}
]
}
3. Create an Activity of Type "Email"
We will prepare the variables:
-
contactEmail— the first element from theresultContactcontact, -
staff— the first element from theresultUserobject.
let contactEmail = resultContact.EMAIL[0];
let staff = resultUser[0];
$contactEmail = reset($resultContact['result']['EMAIL']);
$staff = reset($resultUser['result']);
To add the event and send the email, we will use the method crm.activity.add. We need to pass the client's data, the employee's data, and the activity parameters.
-
SUBJECT— the email subject. We will specifysubject email now. -
DESCRIPTION— the email body. For example,body email now. -
DESCRIPTION_TYPE— the text type. Possible values:1— plain text,2— HTML markup,3— BB-code. We will set the value to3. -
COMPLETED— a flag indicating whether the event is completed. We will specifyY. -
DIRECTION— the direction of the activity. We will pass2— outgoing email. A complete list of activity directions can be obtained using the method crm.enum.activitydirection. -
OWNER_ID— the contact identifier. We will pass the variablecontactID. -
OWNER_TYPE_ID— the identifier of the CRM object type. We will pass3— contact. A complete list of object types can be obtained using the method crm.enum.ownertype. -
TYPE_ID— the activity type. We will specify4— email. The list of activity types can be obtained using the method crm.enum.activitytype. -
COMMUNICATIONS— the client's contact details:-
VALUE— the email address, taking theVALUEfrom thecontactEmailarray, -
ENTITY_ID— the client identifier, passingcontactID, -
ENTITY_TYPE_ID— the identifier of the object type, passing3— contact.
-
-
START_TIMEandEND_TIME— the start and end date and time of the activity. We will specify a duration of 1 hour. -
RESPONSIBLE_ID— the identifier of the responsible person, passingstaff.ID. -
SETTINGS— additional settings:MESSAGE_FROM— the email sender, passing the namestaff.NAME, last namestaff.LAST_NAME, and email addressstaff.EMAILof the employee.
BX24.callMethod(
'crm.activity.add',
{
'fields': {
"SUBJECT": "subject email now",
"DESCRIPTION": "body email now",
"DESCRIPTION_TYPE": 3,
"COMPLETED": "Y",
"DIRECTION": 2,
"OWNER_ID": contactID,
"OWNER_TYPE_ID": 3,
"TYPE_ID": 4,
"COMMUNICATIONS": [
{
'VALUE': contactEmail.VALUE,
'ENTITY_ID': contactID,
'ENTITY_TYPE_ID': 3
}
],
"START_TIME": new Date().toISOString(),
"END_TIME": new Date(Date.now() + 3600 * 1000).toISOString(),
"RESPONSIBLE_ID": staff.ID,
'SETTINGS': {
'MESSAGE_FROM': `${staff.NAME} ${staff.LAST_NAME} <${staff.EMAIL}>`
}
}
}
);
$resultActivity = CRest::call(
'crm.activity.add',
[
'fields' => [
"SUBJECT" => "subject email now",
"DESCRIPTION" => "body email now",
"DESCRIPTION_TYPE" => 3,//text,html,bbCode type id in: CRest::call('crm.enum.contenttype');
"COMPLETED" => "Y",//send now
"DIRECTION" => 2,// CRest::call('crm.enum.activitydirection');
"OWNER_ID" => $contactID,
"OWNER_TYPE_ID" => 3, // CRest::call('crm.enum.ownertype');
"TYPE_ID" => 4, // CRest::call('crm.enum.activitytype');
"COMMUNICATIONS" => [
[
'VALUE' => $contactEmail['VALUE'],
'ENTITY_ID' => $contactID,
'ENTITY_TYPE_ID' => 3// CRest::call('crm.enum.ownertype');
]
],
"START_TIME" => date("Y-m-d H:i:s", time()),
"END_TIME" => date("Y-m-d H:i:s", time() + 3600),
"RESPONSIBLE_ID" => $staff['ID'],
'SETTINGS' => [
'MESSAGE_FROM' => implode(
' ',
[$staff['NAME'], $staff['LAST_NAME'], '<' . $staff['EMAIL'] . '>']
),
],
]
]
);
If the event is successfully created, the method will return its identifier. If you receive an error, refer to the documentation for the method crm.activity.add for possible error descriptions.
{
"result": 3165,
}
Complete Code Example
The code in the example combines all steps: retrieves the client and employee data, adds the "Email" activity, and sends the email to the client.
document.addEventListener('DOMContentLoaded', function() {
async function createEmailActivityForContact() {
try {
let contactID = 1;
let resultContact = await new Promise((resolve, reject) => {
BX24.callMethod(
'crm.contact.get',
{ 'id': contactID },
function(result) {
if (result.error()) {
reject(result.error());
} else {
resolve(result.data());
}
}
);
});
if (resultContact && resultContact.ASSIGNED_BY_ID && resultContact.EMAIL) {
let resultUser = await new Promise((resolve, reject) => {
BX24.callMethod(
'user.get',
{
'filter': {
'ID': resultContact.ASSIGNED_BY_ID
}
},
function(result) {
if (result.error()) {
reject(result.error());
} else {
resolve(result.data());
}
}
);
});
if (resultUser.length > 0) {
let contactEmail = resultContact.EMAIL[0];
let staff = resultUser[0];
if (contactEmail.VALUE && staff.EMAIL) {
let resultActivity = await new Promise((resolve, reject) => {
BX24.callMethod(
'crm.activity.add',
{
'fields': {
"SUBJECT": "subject email now",
"DESCRIPTION": "body email now",
"DESCRIPTION_TYPE": 3,
"COMPLETED": "Y",
"DIRECTION": 2,
"OWNER_ID": contactID,
"OWNER_TYPE_ID": 3,
"TYPE_ID": 4,
"COMMUNICATIONS": [
{
'VALUE': contactEmail.VALUE,
'ENTITY_ID': contactID,
'ENTITY_TYPE_ID': 3
}
],
"START_TIME": new Date().toISOString(),
"END_TIME": new Date(Date.now() + 3600 * 1000).toISOString(),
"RESPONSIBLE_ID": staff.ID,
'SETTINGS': {
'MESSAGE_FROM': `${staff.NAME} ${staff.LAST_NAME} <${staff.EMAIL}>`
}
}
},
function(result) {
if (result.error()) {
reject(result.error());
} else {
resolve(result.data());
}
}
);
});
if (resultActivity) {
console.log(JSON.stringify({ 'message': 'Activity added' }));
} else {
console.log(JSON.stringify({ 'message': 'Activity not added' }));
}
}
}
}
} catch (error) {
console.error(error);
console.log(JSON.stringify({ 'message': 'Activity not added: ' + error.message }));
}
}
createEmailActivityForContact();
});
<?php
$contactID = 1;
$resultContact = CRest::call(
'crm.contact.get',
[
'id' => $contactID
]
);
$resultActivity = [];
if (!empty($resultContact['result']['ASSIGNED_BY_ID']) && !empty($resultContact['result']['EMAIL']))
{
$resultUser = CRest::call(
'user.get',
[
'filter' => [
'ID' => $resultContact['result']['ASSIGNED_BY_ID']
]
]
);
if ($resultUser['result'])
{
$contactEmail = reset($resultContact['result']['EMAIL']);
$staff = reset($resultUser['result']);
if (!empty($contactEmail['VALUE']) && !empty($staff['EMAIL']))
{
$resultActivity = CRest::call(
'crm.activity.add',
[
'fields' => [
"SUBJECT" => "subject email now",
"DESCRIPTION" => "body email now",
"DESCRIPTION_TYPE" => 3,//text,html,bbCode type id in: CRest::call('crm.enum.contenttype');
"COMPLETED" => "Y",//send now
"DIRECTION" => 2,// CRest::call('crm.enum.activitydirection');
"OWNER_ID" => $contactID,
"OWNER_TYPE_ID" => 3, // CRest::call('crm.enum.ownertype');
"TYPE_ID" => 4, // CRest::call('crm.enum.activitytype');
"COMMUNICATIONS" => [
[
'VALUE' => $contactEmail['VALUE'],
'ENTITY_ID' => $contactID,
'ENTITY_TYPE_ID' => 3// CRest::call('crm.enum.ownertype');
]
],
"START_TIME" => date("Y-m-d H:i:s", time()),
"END_TIME" => date("Y-m-d H:i:s", time() + 3600),
"RESPONSIBLE_ID" => $staff['ID'],
'SETTINGS' => [
'MESSAGE_FROM' => implode(
' ',
[$staff['NAME'], $staff['LAST_NAME'], '<' . $staff['EMAIL'] . '>']
),
],
]
]
);
}
}
}
if (!empty($resultActivity['result']))
{
echo json_encode(['message' => 'Activity added']);
}
elseif (!empty($resultActivity['error_description']))
{
echo json_encode(['message' => 'Activity not added: ' . $resultActivity['error_description']]);
}
else
{
echo json_encode(['message' => 'Activity not added']);
}
?>