User Notification Settings

Introduction

The RESTful API email communication flows between requests submitted and any given result, regardless of a successful or error outcome. Notifications received from the API can be customized by users via the /user/setting/notification resource, which provides an interface to enable or disable emails of the following types with the /user/setting/notification/request:

Submission: any PUT, POST, DELETE or PATCH action will trigger an email notification as a summary of the request. Users can enable or disable receiving emails upon any submission.
Completion: any PUT, POST, DELETE or PATCH action creates an asynchronous task and the API sends a notification to users summarizing the successful result. Users can enable receiving emails when a request succeeded.
Error: any PUT, POST, DELETE or PATCH action creates an asynchronous task and the API sends a notification to users summarizing errors in results. Users can enable receiving just emails when a request has failed.

And customize which notification format /user/setting/notification/format between HTML or TEXT.

On this page:

The following table shows a brief description and HTTP methods allowed to interact with the user email settings data:

Resource	URI	Description
Notification format	/user/setting/notification/format	Notification format (html or text)
Request notification settings	/user/setting/notification/request	Request notification settings

TK stores the Cloud API Token generated as a result of the following POST request to the /auth/request-token resource:

curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username>

For example, extracting the token with the jq command:

TK=$(curl -X POST https://vss-api.eis.utoronto.ca/auth/request-token -u <username> | jq '.token')

List

To list your account notification settings, just do a GET request to /user/setting/notification as follows:

http GET "https://vss-api.eis.utoronto.ca/v2/user/setting/notification" "Authorization: Bearer $TK"
curl -X GET -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/user/setting/notification"

The response would look something like:

{
    "_links": {
        "notification_format": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/format",
        "notification_method": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/method",
        "notification_request": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request",
        "self": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification",
        "settings": "https://vss-api.eis.utoronto.ca/v2/user/setting"
    },
    "data": {
        "format": "text",
        "method": "mail",
        "request": {
            "all": false,
            "completion": true,
            "error": true,
            "none": false,
            "submission": true
        }
    },
    "meta": {
        "count": 3,
        "time": "0.00259s",
        "user": "jm"
    }
}

Disable All request notification

To disable all request notification (not recommended), submit the following PUT request:

http PUT "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request" attribute=none value:=true "Authorization: Bearer $TK"
curl -X PUT -H "Authorization: Bearer $TK" "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request" -d '{"attribute": "none", "value": True}'

{
    "_links": {
        "notification": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification",
        "self": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request"
    },
    "data": {
        "all": false,
        "completion": false,
        "error": false,
        "none": true,
        "submission": false
    },
    "meta": {
        "count": 5,
        "time": "0.00196s",
        "user": "jm"
    }
}

Enable All email notification

To enable only all email notification, submit the following PUT requests:

# httpie
http PUT "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request" attribute=all value:=true "Authorization: Bearer $TK"

# curl
curl -X PUT -H "Authorization: Bearer $TK" -H "Content-Type: application/json" "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request" -d '{"attribute": "all", "value": True}'

{
    "_links": {
        "notification": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification",
        "self": "https://vss-api.eis.utoronto.ca/v2/user/setting/notification/request"
    },
    "data": {
        "all": true,
        "completion": false,
        "error": false,
        "none": false,
        "submission": false
    },
    "meta": {
        "count": 5,
        "time": "0.00196s",
        "user": "jm"
    }
}