Creating Your Sendloop App

INTRODUCTION

Installing Developer

After you've logged into the Sendloop Dashboard, click Apps in the top navigation bar. Using the drop-down menu that appears, click App Store.

In the App Store, search for the Developer App, and Install it.

You'll be asked to grant access permissions to Developer. Click Accept to continue.

Sendloop will now install Developer onto your account. When complete, you'll be prompted to provide some basic information about yourself. This appears in your Sendloop Developer Profile.

Create Your App

At this point, you'll start creating your app. Begin by providing the name and App URL (this is where your app will be executed) for your soon-to-be app, and click Create a new app to proceed.

App URL

The App URL can be either a publicly accessible domain/IP or simply localhost. However, it must use the HTTPS protocol to ensure security and privacy. Additionally, we recommend that you use ngrok (which opens a secure tunnel to your localhost) during the development process.

Once Sendloop creates your new app, you'll be directed to the app's control page.

You can manage every aspect of your app using the control page, including the app profile (name, description, banner appearance, and so on) and the app execution parameters.

Name

Name of your app; this will be shown to you and (if the app is public) to other Sendloop users

Short Description

Explanation of what your app does

Banner

A 260 x 130 pixel banner to display in the App Store

Icon

A 130 x 130 icon for your app

App URL

The https URL where your app runs

App Type

Your app's type:

  • Embedded: runs inside Sendloop; users can access and use your app within their Sendloop accounts
  • External: runs in a new browser window to which your users are redirected

Client ID

Unique ID of your app

Client Secret

Secret key for your app

Embedded vs. External Apps

There are two types of apps in the App Store.

Embedded Apps: Runs inside Sendloop. When the user clicks Use, your app opens inside the Sendloop user interface.

External Apps: Runs on your own infrastructure or website. When the user clicks Use, your app gets redirected to the app via browser window.

Generally, we recommend building an embedded app. Because the user never leaves Sendloop, his or her interaction with your app will be that much smoother.

Requirements for Embedded Apps

Currently, we have two requirements for building an embedded Sendloop app:

  1. You must use the Bootstrap CSS Framework.
  2. You must use the Sendloop App JavaScript SDK.

By using these tools, your embedded app will look like a native Sendloop feature, improving the users' overall UX.

The JavaScript SDK

If you are developing an embedded app, use the JavaScript SDK to make sure it complies with Sendloop's standards. The JavaScript SDK also provides additional features to your app so that the user experience is as seamless as possible:

  1. App frame navigation bar preferences management, including those for breadcrumbs, links, buttons, drop-down menus, and progress bars;
  2. Modals, including the confirmation and prompt windows.

Including the JavaScript SDK in Your App

To include the JavaScript SDK file in your app, place the following in the <head> block of your app's HTML file:

<script src="https://assets.mailium.net/js/sdk.min.js"></script>

Accessing SDK Features

Before you access the SDK's features, be sure to initiate the SDK with your user's account and app IDs:

MailiumApp.init({
    accountID: 'ACCOUNT-ID-HERE',
    appID: 'APP-ID-HERE'
});
  • ACCOUNT-ID-HERE : Replace with the accid received when the authorization is made (see below for additional authorization information)
  • APP-ID-HERE : Available on your application details page under "Application ID" title.

You should use all SDK features within a callback that indicates if the app is ready:

MailiumApp.ready(function () {
    // ...
});

SDK Features

Toggling Progress Bars on the App Frame's Nav Bar

Since your app runs in an iframe, users may not notice interactions (such as navigating to a different page) that occur inside. Because of this, displaying the progress bar would be useful.

  • To display progress bar: MailiumApp.loadingOn();
  • To hide the progress bar: MailiumApp.loadingOff();

Sendloop Developer App

Changing the Breadcrumb in the App's Nav Header

To show your users where they are in your app, you can use breadcrumbs in the app's nav header.

MailiumApp.setBreadcrumb([
    MailiumApp.element.link('Dashboard', '#link-url-here')
]);

Sendloop Developer App

Please note that the breadcrumbs are reset each time the page loads or reloads within its frame. Because of this, you might need to configure breadcrumbs to display appropriately on each page load.

You can add "MailiumApp.element.link" and "MailiumApp.element.text" elements
to breadcrumb. You can find more information on how to use these elements at the end
of this article.

Setting Navigation Header's Buttons, Links, and Drop-Down Menus
MailiumApp.setBar([
    MailiumApp.element.text('Hi user!'),
    MailiumApp.element.button('Create new item', function() {
        console.log('clicked on create new item button');
    }, 'success')
]);

Sendloop Developer App

You can add "MailiumApp.element.link", "MailiumApp.element.button" and
"MailiumApp.element.dropdown" elements to nav bar. You can find more information
on how to use these elements at the end of this article.

Adding Modal Windows

Here's how to display a confirmation modal to your app:

MailiumApp.popupConfirm({
    title: '',
    message: '',
    confirmButton: '',
    cancelButton: '',
    size: 'small'
}, function () {
    // confirm
}, function () {
    // reject
});

Here's how to display a prompt modal window to your app:

MailiumApp.popupInput({
    title: '',
    message: '',
    submitButton: '',
    cancelButton: '',
    size: 'small'
}, function (data) {
    // submit
    var parsedData = JSON.parse(data),
        promptValue = parsedData.value;
}, function () {
    // cancel
});

Element Types Available

Text: MailiumApp.element.text('text here');

Link: MailiumApp.element.link('link title here', 'http://...');

```MailiumApp.element.link('link with callback', function() {
console.log('clicked on link');
});


**Button**: `MailiumApp.element.button('button label', 'http://...', 'success');`

MailiumApp.element.button('button label', function() {
console.log('clicked on button');
}, 'danger');


The third parameter is the button style. You can choose one of the following: danger, success, primary,default.

**Dropdown**
```MailiumApp.element.dropdown('dropdown label', [
    MailiumApp.element.link('link title here', 'http://...'),
    MailiumApp.element.seperator(),
    MailiumApp.element.link('second link title here', 'http://...')
], 'success');

Dropdown elements can accept only the "MailiumApp.element.link" and "MailiumApp.element.seperator" elements.

Seperator: MailiumApp.element.seperator();

Implementing Authentication

Whenever a user installs your app, Sendloop redirects the user to your app with the following URL parameters: accid, timestamp, hmac.

To complete the authentication process, your app must follow these steps:

  1. Validate the request using the HMAC algorithm.
  2. Check the user's account based on his or her accid parameter.
  3. Validate the OAuth token.

If your app finds a user account with the provided accid and the OAuth token is valid, your app should continue the installation process so that the user can use it.

If you cannot find the user account with the provided accid or the OAuth token is valid, your app should redirect the user to the authorization endpoint using the authorization code grant so that the user can grant your app access to his or her Sendloop account. Once the user approves your app's authentication request, Sendloop will redirect the user to your app again. Server-side, your app should request the token from the Token endpoint.

Uninstall Requests

If the user makes an uninstall request to your app, you must delete any data related to the Sendloop user.

After your app has retrieved the token, it should save it for future use. The token is active until the user revokes access or uninstalls the app.

OAuth Grants

The OAuth server accepts the following grants:

  1. The Authorization Code Grant
  2. The Refresh Token Grant

The Authorization API

This section contains information about the Authorization API's endpoints, including it's URL, a description of what you would use it for, required and response parameters, and samples.

Authorization - https://oauth.mailium.net/oauth/authorize

This end point is used to get the Authorization Code via authorization code grant and is the first step towards getting the access token. This redirects the user to the authorization web page which user will review the requested scopes. User has two options: approve or decline.

Required Parameters

  1. response_type: with value of "code"
  2. client_id: your application's client_id
  3. redirect_uri: your application's URL
  4. scope: your applications' required scopes
  5. state: nonce (learn more)

Response Parameters

  1. code
  2. state

Sample Request

curl -X "GET" "https://oauth.mailium.net/oauth/authorize?response_type=code&client_id=$CLIENT_ID$&redirect_uri=$REDIRECT_URI$&scope=$SCOPE1$%20$SCOPE2$&state=$STATE$" -H "Content-Type: application/x-www-form-urlencoded"

Sample Response

Once user approves, server will redirect user to your application with the authorization code. This code will be used to retrieve the access token.

Retrieving Authentication Token - https://oauth.mailium.net/oauth/token

Used to obtain the access token once the required authorization code has been received

Required Parameters

  1. grant_type with the value of 'authorization_code'
  2. client_id
  3. client_secret
  4. redirect_uri
  5. code

Response Parameters

  1. token_type with the value of Bearer
  2. expires_in
  3. access_token
  4. refresh_token

Sample Request

curl -X "POST" "https://oauth.mailium.net/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
--data-urlencode "code=$AUTHORIZATION_CODE$" \
--data-urlencode "client_id=$CLIENT_ID$" \
--data-urlencode "client_secret=$CLIENT_SECRET$" \
--data-urlencode "redirect_uri=$REDIRECT_URI$" \
--data-urlencode "grant_type=authorization_code"

Sample Response

Response is returned as a JSON object:

{
  "token_type": "Bearer",
  "expires_in": "$TOKEN_EXPIRES_IN_SECONDS$",
  "access_token":"$ACCESS_TOKEN$",
  "refresh_token":"$REFRESH_TOKEN$"
}

New Authentication Token Request with Refresh Token - https://oauth.mailium.net/oauth/token

If the existing access token is expired or invalid, you can use the refresh token to get a new access token/refresh token pair.

Required Parameters

  1. response_type with value of "refresh_token"
  2. refresh_token => your application's client_id
  3. client_id => your application's client_id
  4. client_secret => your application's client_secret
  5. scope => your applications' required scopes
  6. state => nonce

Response Parameters

  1. token_type with the value of "Bearer"
  2. expires_in
  3. access_token
  4. refresh_token

Sample Request

curl -X "POST" "https://oauth.mailium.net/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
--data-urlencode "client_id=$CLIENT_ID$" \
--data-urlencode "client_secret=$CLIENT_SECRET$" \
--data-urlencode "refresh_token=$REFRESH_TOKEN$" \
--data-urlencode "grant_type=refresh_token"

Sample Response

Response is returned as a JSON object:

{
    "token_type": "Bearer",
    "expires_in": "$TOKEN_EXPIRES_IN_SECONDS$",
    "access_token":"$ACCESS_TOKEN$",
    "refresh_token":"$REFRESH_TOKEN$"
}

Authentication Token Revoke - https://oauth.mailium.net/oauth/revoke

Used when user requests an uninstall or the application needs to revoke both the access and refresh token.

Sample Request

curl -X "GET" "https://oauth.mailium.net/revoke" \
-H "Authorization: Bearer $ACCESS_TOKEN$" \
-H "Content-Type: application/json"

Sample Response

HTTP Status code 200 is returned without any data.

Resource Owner - https://oauth.mailium.net/resource

Returns the current resource owner's account ID.

Sample Request

curl -X "GET" "https://oauth.mailium.net/resource" \
-H "Authorization: Bearer $ACCESS_TOKEN$" \
-H "Content-Type: application/json"

Sample Response

Response is JSON-encoded object that contains accid. This accid (account id) is the unique identifier of the user/account.

{
  "accid": "user-subdomain.$domain$.$tld$"
}

Authorizing API Requests

Once you've authorized and retrieved the access token, you will need to pass it to the appropriate API endpoints.

The header of your request must begin with BEARER and be followed by the access token:

curl -X "GET|POST" "https://$ACCID$/$API_VERSION$/$API_COMMAND$" \
    -H "Authorization: Bearer $ACCESS_TOKEN$" \
    -H "Content-Type: application/json"

Verifying Responses

Every response from Sendloop to your application includes the following values:

  1. accid: the user or account id
  2. timestamp: the timestamp of the request
  3. hmac: the HMAC calculation

To validate the request, you can use the HMAC calculation and algorithm. You can do so using the following steps:

  1. Get the query string from the request
  2. Parse the query string into key-value pairs
  3. Make following replacements in the key-value pairs:

    • Replace "%" with "%25" on keys and values
    • Replace "&" with "%26" on keys and values
    • Replace "=" with "%3D" on keys
  4. Remove the HMAC key from the array

  5. Sort the array map by keys lexicographically
  6. Concatenate the array to generate a string (e.g. key=value&key2=value2)
  7. Generate a keyed hash value using the HMAC method SHA256
  8. Validate the HMAC received and HMAC generated. They should match.

Example: Validating HMAC

This is an example of how to validate HMAC using PHP.

function verifyHmac ($data, $hmacKey)
    {
        if (is_array($data)) {
            // Convert the query string to an array
            $queryString = http_build_query($data);
        } else {
            $queryString = $data;
        }

        parse_str($queryString, $dataMap);

        $hmacMap = array();
        foreach ($dataMap as $dataKey => $dataValue) {
            $key = str_replace('%', '%25', $dataKey);
            $value = str_replace('%', '%25', $dataValue);

            $key = str_replace('&', '%26', $key);
            $value = str_replace('&', '%26', $value);

            $key = str_replace('=', '%3D', $key);

            $hmacMap[$key] = $value;
        }

        $hmacFromRequest = $hmacMap['hmac'];
        unset($hmacMap['hmac']);

        // Sort the array map
        ksort($hmacMap);

        $hmacString = http_build_query($hmacMap);

        $digest = hash_hmac('sha256', $hmacString, $hmacKey);

        return $hmacFromRequest === $digest;
    }

Client Libraries

We have prepared the following libraries for your use:

If you're using a different platform/framework/programming language, please refer to Chapter 5 for information on the OAuth Authentication API endpoints.

The OAuth server is also compatible with the PHP League's oauth2-client library.

Creating Your Sendloop App