Recipient groups

01. Add recipients to group

Back to top

Add recipients to recipient group

POST /int/v1/recipientGroup/:id/recipients

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) Recipient group id value
recipientIds	String[]	optional The recipient id string array. Mutually exclusive with recipientEmails
recipientEmails	String[]	optional the recipient email string array, case insensitive. Mutually exclusive with recipientIds
reset	Boolean	optional reset the group existing recipients

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X POST https://<url>/int/v1/recipientGroup/<id>/recipients \
     -d '{"recipientEmails": ["john@communic8.com"]}'

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/recipientGroup/${id}/recipients`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              recipientEmails: [
                "john@communic8.com"
              ] 
            }
          )
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.GROUP_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalResult object. Present when success is true.
data.successCount	Number	optionalNumber of recipients successfully added.
data.errorCount	Number	optionalNumber of recipients failed to add.
data.errorLog	Object[]	optionalError log array. Present when errorCount > 0.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success (recipients added to group):

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "successCount": 1,
    "errorCount": 0,
    "errorLog": []
  }
}

Success response example - Success (recipients already in group):

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "successCount": 0,
    "errorCount": 0,
    "errorLog": []
  }
}

Success response example - Error (recipients not found):

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Not all emails founded as recipient in system"
}

02. Remove recipients from group

Back to top

Remove recipients from recipient group

DELETE /int/v1/recipientGroup/:id/recipients

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) recipient group id
recipientIds	Array	optional the recipient id string array. Mutually exclusive with recipientEmails
recipientEmails	Array	optional the recipient email string array, case insensitive. Mutually exclusive with recipientIds

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X DELETE https://<url>/int/v1/recipientGroup/<id>/recipients \
     -d '{"recipientEmails": ["john@communic8.com"]}'

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/recipientGroup/${id}/recipients`,
        {
          method: "DELETE",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              recipientEmails: [
                "john@communic8.com"
              ] 
            }
          )
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.GROUP_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalResult object. Present when success is true.
data.successCount	Number	optionalNumber of recipients successfully added.
data.errorCount	Number	optionalNumber of recipients failed to add.
data.errorLog	Object[]	optionalError log array. Present when errorCount > 0.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success (recipients in group):

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "successCount": 1,
    "errorCount": 0,
    "errorLog": []
  }
}

Success response example - Success (recipients not in group):

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "successCount": 0,
    "errorCount": 0,
    "errorLog": []
  }
}

Success response example - Error (recipients not found):

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Not all emails founded as recipient in system"
}

03. List recipient groups

Back to top

List recipient groups the user is authorised to view (supports page query syntax and search by 'name')

GET /int/v1/recipientGroup

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Query Parameters

Name	Type	Description
limit	String	optional Maximum number of records to return.Default value: 20
skip	String	optional Skip this number of records. For pagination.Default value: 0
own	String	optional Filter by own groups (true/false)

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/recipientGroup

Javascript Example:

(async (url, token) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/recipientGroup`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object[]	optionalRecipient group objects. Present when success is true.
total	Number	optionalTotal number of recipient groups. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": [
    {
      "_id": "664294699235fbd93ca1cc17",
      "name": "My group",
      "exclusive": true,
      "leads": [
        "6304601198ed1f21a6219337"
      ],
      "leadsTotal": 1,
      "ownerId": "635b559a1da40d7f27ea0f14",
      "mDate": "2024-05-13T22:30:01.378Z",
      "aDate": "2024-05-13T22:30:01.378Z",
      "__v": 0
    }
  ],
  "total": 1
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"pb_c_list validation failed: name: Path `name` is required."
}

04. Get a recipient group

Back to top

Read recipient group detail by ID

GET /int/v1/recipientGroup/:id

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) Recipient group id

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/recipientGroup/<id>

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/recipientGroup/${id}`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.GROUP_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalRecipient group object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "_id": "664294699235fbd93ca1cc17",
    "name": "My group",
    "exclusive": true,
    "leads": [
      "6304601198ed1f21a6219337"
    ],
    "leadsTotal": 1,
    "ownerId": "635b559a1da40d7f27ea0f14",
    "mDate": "2024-05-13T22:30:01.378Z",
    "aDate": "2024-05-13T22:30:01.378Z",
    "__v": 0
  }
}

Error response example

Error response example - Error:

HTTP/1.1 404 Not Found
Not Found

05. Create a recipient group

Back to top

Create a recipient group

POST /int/v1/recipientGroup

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Request Body

Name	Type	Description
name	String	Recipient group name
leads	String[]	optional List of recipient _id values to add to new group.

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X POST https://<url>/int/v1/recipientGroup \
     -d '{"name": "My group"}'

Javascript Example:

(async (url, token) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/recipientGroup`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              name: "My group"
            }
          )
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalRecipient group object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "_id": "664294699235fbd93ca1cc17",
    "name": "My group",
    "exclusive": true,
    "leads": [
      "6304601198ed1f21a6219337"
    ],
    "leadsTotal": 1,
    "ownerId": "635b559a1da40d7f27ea0f14",
    "mDate": "2024-05-13T22:30:01.378Z",
    "aDate": "2024-05-13T22:30:01.378Z",
    "__v": 0
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"pb_c_list validation failed: name: Path `name` is required."
}

06. Delete recipient group

Back to top

Delete recipient group record by id

DELETE /int/v1/recipientGroup/:id

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Parameter) id Recipient group id

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X DELETE https://<url>/int/v1/recipientGroup/<id>

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/recipientGroup/${id}`,
        {
          method: "DELETE",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.GROUP_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalRecipient group object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "_id": "664294699235fbd93ca1cc17",
    "name": "My group",
    "exclusive": true,
    "leads": [],
    "leadsTotal": 0,
    "ownerId": "635b559a1da40d7f27ea0f14",
    "mDate": "2024-05-13T22:30:01.378Z",
    "aDate": "2024-05-13T22:30:01.378Z",
    "__v": 0
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Object does not exist"
}