About this tutorial

CIP provides APIs allowing you to send e-mail notifications to users in two ways:

• Send notifications to users within the current customer context (user notification API).

• Send notifications to all users across multiple customers (customer notification API).

Following this tutorial, you can try out the customer notification API. You’re going to perform the following actions:

1. Authenticate to CIP to get an SSO token.

2. Send a customer-based notification request to CIP using the received token.

Prerequisites

• CIP up and running

• Administrator account in CIP with the ADMIN_SEND_CUSTOMERS_NOTIFICATION_MESSAGE entitlement

Send notifications to customers

1. Authenticate to CIP as an administrator by sending a request to https://example.com/api/authn/identifierpassword.

   • Replace example.com with your actual CIP domain.

   • Set identifier and password to your own credentials.

   curl --verbose POST 'https://example.com/api/authn/identifierpassword' \
   --header 'Content-Type: application/json' \
   --data-raw '{
   "identifier": "YOUR_IDENTIFIER",
   "password": "t0ps3cr3t"
   }'
   

   Result

   Authorization token is returned in the response body (code 201 is returned). Save this token.

   < HTTP/2 201
   < date: Tue, 08 Jun 2021 12:41:01 GMT
   < content-type: application/json
   < content-length: 48
   < server: nginx
   < trace-id: 23b5a553fb95a19c
   < access-control-allow-credentials: true
   < access-control-allow-headers: *
   < access-control-allow-methods: *
   < access-control-max-age: 600
   <
   * Connection #0 to host example.com left intact
   {"token":"0d25bdba-009b-47a9-a985-554692572b1e"}* Closing connection 0
   

   More information

   You can read more about authentication options in the REST API authentication documentation.

2. Send a notification request to the https://example.com/api/customers/notify/email endpoint. Provide the following data in the body:

   • target (required) - which users should receive the e-mail. Can be ALL_USERS (all users in all organizations) or SELECTED_CUSTOMER_USERS (users belonging to specific organizations only).

   • identifiers - complementary information to target. Specifies which users should receive the e-mail based on their parent organization. If target is set to ALL_USERS, this information is redundant (notifications are sent regardless of the organization). Use customer IDs (cid) as identifiers.

   • emailParams (required) - defines which template to use and what the e-mail subject is. templateId must point to a template available in your CIP deployment (for details, see Configuring notification templates).

   • emailContent - data related to the contents of the e-mail.

   All parameters and their options are explained in the API documentation for customer notifications.

   curl --location --request POST 'https://example.com/api/customers/notify/email' \
   --header 'token: 0d25bdba-009b-47a9-a985-554692572b1e' \
   --header 'Content-Type: application/json' \
   --data-raw '{
    "target": "SELECTED_CUSTOMER_USERS",
    "identifiers": ["cloudentity"],
    "emailParams": {
        "templateId": "testnotification",
        "subject": "Subject"
    },
    "emailContent": {
        "title": "title",
        "subtitle": "subtitle",
        "body": "E-mail body",
        "links": ["www.someurl.com"]
    }
   }'
   

   Result

   Users in the selected organization (cloudentity in the above example) receive e-mails as specified in the emailParams and emailContent objects.

Related articles

Having tried out the customer notification API, you might be interested in the following articles:

• Sending notifications to users

• Configuring notification templates