Working With Jet Email Notifications

Email notification subscriptions allow users to receive notifications about a job's transfer activity. Subscriptions created via the API can set which specific notifications are sent and received by a recipient by sending a request to the /v1/subscriptions endpoint.

The transfer email notifications sent to a recipient depend on the event type included in the eventTypes array in the request body used to create a subscription.

Enabling email notifications via the Signiant Console creates a subscription that includes all three transfer event types related to the job.

Note: Email notifications can only be sent to members of your Jet account.

Hot Folder Transfer Summary Emails

Hot folder Transfer summary emails can be aggregated by including an aggregationConfig to the notificationConfig object to prevent an overwhelming amount of emails when transferring large data sets. The aggregationConfig accepts an aggregationWindowInSeconds parameter to set the aggregation period for notifications related to hot folder transfers.

When a transfer event happens, an email summary of all completed events included in that hot folder job will be sent to recipients at the end of the selected aggregationWindowInSeconds notification period. Any additional transfers that complete during that period are also included in the notification email.

Subscribing to Email Notifications

Hot Folder Jobs

1. Send a GET request to /v1/jobs to retrieve a list of jobs.

    > curl -X GET -H "Authorization: Bearer <token>" -H "Content-Type: application/json" https://  platform-api-service.services.cloud.signiant.com/v1/jobs

2. Use the response body to determine the jobId required for the /v1/subscriptions endpoint request.

3. Create a request body including the jobId, and eventTypes as part of the eventFilterConfig, the notificationMethod as "EMAIL", and the setting the recipients and aggregationConfig within the notificationConfig object:

   {
     "eventCategory": "JET_TRANSFER",
     "eventFilterConfig": {
       "jobId": "12345678-1234-abba-4321-123456789ec6",
       "eventTypes": [
         "com.signiant.jet.transfer.failed",
         "com.signiant.jet.transfer.canceled",
         "com.signiant.jet.transfer.completed"
       ]
     },
     "notificationMethod": "EMAIL",
     "notificationConfig": {
       "recipients": ["user@example.com"],
       "aggregationConfig": {
         "aggregationWindowInSeconds": 1800
       }
     }
   }

4. Send the request body to the /v1/subscriptions API endpoint to create the subscription and enable notifications.

Manual / Scheduled Jobs

1. Send a GET request to /v1/jobs to retrieve a list of jobs.

    > curl -X GET -H "Authorization: Bearer <token>" -H "Content-Type: application/json" https://  platform-api-service.services.cloud.signiant.com/v1/jobs

2. Use the response body to determine the jobId required for the /v1/subscriptions endpoint request.

3. Create a request body including the jobId, and eventTypes as part of the eventFilterConfig, the notificationMethod as "EMAIL", and the setting the recipients:

   {
     "eventCategory": "JET_DELIVERY",
     "eventFilterConfig": {
       "jobId": "12345678-1234-abba-4321-123456789ec6",
       "eventTypes": [
         "com.signiant.jet.delivery.inProgress",
         "com.signiant.jet.delivery.completed",
         "com.signiant.jet.delivery.failed"
       ]
     },
     "notificationMethod": "EMAIL",
     "notificationConfig": {
       "recipients": ["user@example.com"]
     }
   }

4. Send the request body to the /v1/subscriptions API endpoint to create the subscription and enable notifications.

Subscription Metadata

Email subscriptions may include a metadata object in the request body that describes aspects of the subscription. You can include custom metadata required by your organization related to the job by including keys and values within the metadata object.

Note: Subscription metadata cannot be modified.

Example Response Body

{
  "accountId": "12345678-abcd-abcd-abcd-123456789123",
  "createdOn": "2021-04-14T16:20:21.116Z",
  "eventCategory": "JET_TRANSFER",
  "eventFilterConfig": {
    "jobId": "12345678-1234-abba-4321-123456789ec6",
    "eventTypes": [
      "com.signiant.jet.transfer.failed",
      "com.signiant.jet.transfer.canceled",
      "com.signiant.jet.transfer.completed"
    ]
  },
  "notificationMethod": "EMAIL",
  "subscriptionId": "abcdef12-3456-7890-1234-abcdef123456",
  "notificationConfig": {
    "recipients": ["user@example.com"],
    "aggregationConfig": {
      "aggregationWindowInSeconds": 1800
    }
  },
  "metadata": {
    "customMetadata": "example custom metadata"
  }
}