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 user notification API. You’re going to perform the following actions:

1. Authenticate to CIP to get an SSO token.

2. Send a notification to users within the context of the current customer.

Prerequisites

• CIP up and running

• Administrator account in CIP with the ADMIN_SEND_NOTIFICATION_MESSAGE entitlement

Send notifications to users

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).

   < 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/users/notify/email endpoint. Provide the following data in the body:

   • target (required) - who should receive the e-mail. Can be ALL (all users belonging to the current session customer) or SELECTED (only specific users identified by their UUID - unique user identifier).

   • identifiers - complementary information to target. If target is set to ALL, this information is redundant (e-mails are sent to all users). Use UUIDs 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/users/notify/email' \
   --header 'token: 0d25bdba-009b-47a9-a985-554692572b1e' \
   --header 'Content-Type: application/json' \
   --data-raw '{
    "target": "SELECTED",
    "identifiers": ["UUID1","UUID2"],
    "emailParams": {
        "templateId": "testnotification",
        "subject": "Subject"
    },
    "emailContent": {
        "title": "title",
        "subtitle": "subtitle",
        "body": "E-mail body",
        "links": ["www.someurl.com"]
    }
   }'
   

   Result

   Users identified by UUID1 and UUID2 receive e-mails as specified in the emailParams and emailContent objects.

Related articles

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

• Sending customer-based user notifications

• Configuring notification templates