Notifications

Titan Event Notification

These are the webhooks configured for event notification between from the Titan cloud infrastructure to the partner.

There will be webhooks provided to the Partner for notifications of changes occurring on Titan’s end. All event notification calls will be made until a confirmation of success is received (HTTP 200). In case of failure, Titan will reattempt to push a notification once every minute until Titan receives a confirmation of success. A unique event ID will be passed against each event as a unique identifier in order to prevent duplication. In order to ensure that the events are passed securely, the following measures will be put in place -

The Partner Key will be sent in the Authorization header of all the requests.
Source IPs will be shared with the Partner during deployment

Note - The following IPs will need to be whitelisted by the partner - 3.92.40.244, 34.197.244.225, 52.7.187.26 & 3.64.226.220.

Titan will notify partners on various life cycle events of a Mail Order or an Email Account.

On Mail Order creation at Titan

Note:

noOfAccounts represents the total number of accounts a user has purchased.
customerName, customerEmailAddress, customerCountry, billingCycle are optional fields

json


    {
        "id": "<unique event id>",
        "event": "MAIL_ORDER_CREATED",
        "data":{
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "customerName": "customer name",
            "customerEmailAddress": "customer email address",
            "customerCountry": "< 2 letter ISO CODE, e.g. US>",
            "planType": "<plan-name>",
            "expiryDate": "<utc-expiry-date.format-yyyy-MM-dd>",
            "storageLimit": "<integer-limit-in-mb>",
            "noOfAccounts": "<integer-number-of-accounts-in-plan>",
            "billingCycle": "monthly",
            "status": "active|pending",
            "metadata": {
              "cpanelHostName": "<cPanel hostname where this hosting order provisioned>",
              "cpanelUserName": "<cPanel username associated with this account>"
            }
        }
    }

On Mail Order status update at Titan

Note :

type - type of the suspension like abuse, expiry, employee left
If a domain is suspended with some suspension type then it can only be unblocked by that type only.
suspenderRole - The entity that suspended the email account. It can have following values
- titan
- titanSupport
- partner
- partnerSupport
- domainAdmin - The email account admin that is part of only this domain
- accountAdmin - The Person that get the domain provisioned in the Titan
- account - the email account holder person
suspenderRole have precedence in following order
- (titan , titanSupport) > (partner, partnerSupport) > (domainAdmin, accountAdmin) > account
The higher precedence member can remove the lower precedence member suspension
suspendedOn - suspension date in YYYY-MM-DD format

json

    {
        "id": "<unique event id>",
        "event": "MAIL_ORDER_STATUS_UPDATED",
        "data": {
          "titanOrderId": "<Titan Mail generated unique ID>",
          "domainName": "domain name",
          "customerId": "Unique customer Id on your side for this customer",
          "oldStatus": "active | pending | suspended | deleted",
          "newStatus": "active | suspended | deleted",
          "suspensions": [
            {
                "type": "abuse",
                "suspenderRole": "titanSupport",
                "suspendedOn": "2021-01-13"
            }
          ]
        }
    }

On Mail Order data purge at Titan

Note :

This event will be fired once the mail-order data has been purged. This happens 30 days post the deletion event.
This notification signifies that order data has been permanently deleted and cannot be re-activated.

json

    {
        "id": "<unique event id>",
        "event": "MAIL_ORDER_PURGED",
        "data": {
          "titanOrderId": "<Titan Mail generated unique ID>",
          "domainName": "domain name",
          "customerId": "Unique customer Id on your side for this customer"
        }
    }

On Mail Order Upgrade/Renew at Titan

Note :

Any other events can be added as per Partners requirements.
These events are only send when the billing is managed by Titan for the domain

json

    {
        "id": "<unique event id>",
        "event": "< PLAN_UPGRADED | ACCOUNTS_PURCHASED | PLAN_RENEWED > ",
        "data": {
            "titanOrderId": 1,
            "domainName": "example.com",
            "customerId": "abc",
            "configBeforeUpdate": {
              "planType": "<plan-name>",
              "expiryDate": "<utc-expiry-date.format-yyyy-MM-dd>",
              "storageLimitInMB": "<integer-limit-in-mb>",
              "noOfAccounts": "<integer-number-of-accounts-in-plan>",
              "billingCycle": "monthly"
            },
            "configAfterUpdate": {
              "planType": "<plan-name>",
              "expiryDate": "<utc-expiry-date.format-yyyy-MM-dd>",
              "storageLimitInMB": "<integer-limit-in-mb>",
              "noOfAccounts": "<integer-number-of-accounts-in-plan>",
              "billingCycle": "monthly"
            },
            "paymentDetails": {
              "amount": 10.5,
              "currency": "USD"
            }
        }
    }

On Mail Order Transfer at Titan

Note :

customerBeforeTransfer/customerAfterTransfer are present only when the domain's customer/owner changed as part of the transfer; they are omitted otherwise.
serverBeforeTransfer/serverAfterTransfer are present only when the hosting server changed as part of the transfer; they are omitted otherwise.

json

    {
        "id": "<unique-event-id>",
        "event": "MAIL_ORDER_TRANSFERRED",
        "data": {
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer -- new owner of domain",
            "customerBeforeTransfer": {
                "customerId": "Unique customer Id on your side for this customer",
                "customerName": "customer name",
                "customerEmailAddress": "Email Address of customer",
                "customerCountry": "US"
            },
            "customerAfterTransfer": {
                "customerId": "Unique customer Id on your side for this customer",
                "customerName": "customer name",
                "customerEmailAddress": "Email Address of customer",
                "customerCountry": "IN"
            },
            "serverBeforeTransfer": {
                "titanServerId": "<Titan generated unique server ID>",
                "host": "<hosting server hostname>"
            },
            "serverAfterTransfer": {
                "titanServerId": "<Titan generated unique server ID>",
                "host": "<hosting server hostname>"
            }
        }
    }

On Mail Order Setup Completed at Titan

This is triggered when domain setup has completed.

json

    {
        "id": "<unique-event-id>",
        "event": "MAIL_ORDER_SETUP_COMPLETED",
        "data": {
            "titanOrderId": "<newly created Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "customerName": "customer name",
            "customerEmailAddress": "customer email address",
            "mailService" : "<titan/local>",
            "metadata": {
            "cpanelHostName": "<cPanel hostname where this hosting order provisioned>",
            "cpanelUserName": "<cPanel username associated with this account>"
            }
        }
    }

On Mail Customer Update at Titan

This is triggered when mail customer customerEmail, name or country is updated.

json

    {
        "id": "<unique-event-id>",
        "event": "MAIL_CUSTOMER_UPDATED",
        "data": {
            "customerId": "Unique customer Id on your side for this customer",
            "customerBeforeUpdate": {
                "customerName": "customer name",
                "customerEmailAddress": "Email Address of customer",
                "customerCountry": "US"
            },
            "customerAfterUpdate": {
                "customerName": "New customer name",
                "customerEmailAddress": "New Email Address of customer",
                "customerCountry": "IN"
            }
        }
    }

On Email Account creation or modification at Titan

Note :

name, alternateEmailAddress are optional fields
For EMAIL_ACCOUNT_CREATED, isAdmin and aliases are also optional fields
titanAccountId is the Titan Mail generated unique ID for the email account

json

    {
        "id": "<unique event id>",
        "event": "EMAIL_ACCOUNT_CREATED | EMAIL_ACCOUNT_MODIFIED",
        "data": {
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "email": "<email-address-created>",
            "titanAccountId": "<Titan Mail generated unique ID for this email account>",
            "name": "Name of the user",
            "alternateEmailAddress": "Alternate Email for password reset mails",
            "isAdmin": "true/false",
            "aliases": "list of aliases of email account"
        }
    }

On Email Account status update at Titan

Note :

type - type of the suspension like abuse, expiry, employee left
If an account is suspended with some custom suspension type then it can only be unblocked by that type only.
suspenderRole - The entity that suspended the email account. It can have following values
- titan
- titanSupport
- partner
- partnerSupport
- domainAdmin - The email account admin that is part of only this domain
- accountAdmin - The Person that get the domain provisioned in the Titan
- account - the email account holder person
suspenderRole have precedence in following order
- (titan , titanSupport) > (partner, partnerSupport) > (domainAdmin, accountAdmin) > account
The higher precedence member can remove the lower precedence member suspension
suspendedOn - suspension date in YYYY-MM-DD format

json

    {
        "id": "<unique event id>",
        "event": "EMAIL_ACCOUNT_STATUS_UPDATED",
        "data": {
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "email": "abc@xyz.com",
            "titanAccountId": "<Titan Mail generated unique ID for this email account>",
            "oldStatus": "active | suspended | deleted",
            "newStatus": "active | suspended | deleted",
            "suspensions": [
              {
                  "type":"abuse",
                  "suspenderRole":"titanSupport",
                  "suspendedOn":"2021-01-13"
              }
            ]
        }
    }

On Email Account data purge at Titan

Note :

This event will be fired once the email-account data has been purged. This happens 30 days post the deletion event.
This notification signifies that email-account data has been permanently deleted and this email-account cannot be re-activated.

json

    {
        "id": "<unique event id>",
        "event": "EMAIL_ACCOUNT_PURGED",
        "data": {
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "email": "abc@xyz.com",
            "titanAccountId": "<Titan Mail generated unique ID for this email account>"
        }
    }

On Internal Forwarding Account creation at Titan

Note :

recipients is optional fields

json

    {
        "id": "<unique event id>",
        "event": "INTERNAL_FORWARDING_ACCOUNT_CREATED | INTERNAL_FORWARDING_ACCOUNT_MODIFIED",
        "data": {
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "email": "<email-address-created>",
            "titanAccountId": "<Titan Mail generated unique ID for this email account>",
            "recipients": [
              "email1@xyz.com",
              "email2@xyz.com"
            ]
        }
    }

On Internal Forwarding Account deletion at Titan

json

    {
        "id": "<unique event id>",
        "event": "INTERNAL_FORWARDING_ACCOUNT_DELETED",
        "data": {
            "titanOrderId": "<Titan Mail generated unique ID>",
            "domainName": "domain name",
            "customerId": "Unique customer Id on your side for this customer",
            "email": "<email-address-deleted>",
            "titanAccountId": "<Titan Mail generated unique ID for this email account>"
        }
    }

Titan Control Panel iframe events

To consume the events posted to the container website via window.postMessage() from the embedded Titan Control Panel.

Message structure in titan control panel

Parameters Description:
- event (string, required)
- data (object, optional)

Sample format:

json

{
  "event": "<EVENT_NAME>",
  "data": "<DATA_TO_BE_SENT>"
}

Events Handling in partner panel

Use addEventListener() method to set up a function to be called whenever a message is posted from the iframe to the partner panel.

window.addEventListener("message", (event) => {
    if(event.data.event) {
      //Do needful action here//
    }
}, false);

Events list

These are the standard events sent from Iframe Titan control panel to partner panel.

PAGE_DID_LOAD

Usage

Container websites can show some view or take some action based on the page currently loaded in the iframe. For eg. By listening to the content of the page, you can save events of which pages within the Titan CP your customers visit. Or you could choose to show a dynamic FAQ section that has FAQ's relevant to the page the user is on.
Trigger

Event posted whenever a page is displayed to the user. All pages have been set up to communicate with the parent window via postMessage API.

Example:

json

{
  "event": "PAGE_DID_LOAD",
  "data": {
      "pageName": "<PAGE_NAME>" /* Current path name */
  }
}

PAYMENT_ACTION

Usage

Container websites may choose to redirect the user to the payment URLs in the same tab instead of default behaviour of opening new tabs with payment URLs.
Trigger

Event posted whenever a user takes action related to payments eg: upgrading plan, buying more accounts, renew etc.

Example:

json

{
  "event": "PAYMENT_ACTION",
  "data": {
     "action":"upgradePlan|buyMoreAccounts|renewOrder|billing",
     "titanOrderId": "<Titan Mail generated unique ID>",
     "domainName": "example.com",
     "customerId": "<customerID>",
     "planType": "free|pro|premium",
     "noOfAccounts": "<Total no of current accounts>",
     "expiryDate": "<utc-expiry-date.format-yyyy-MM-dd>"
  }
}

Parameters Description

Parameters	Description	Purpose of the parameter	Data Type
action	Relevant action taken by the customer	This is used to signal the relevant billing option selected by the customer in the Titan control panel. Accordingly, billing and upgrade options should be shown to customers on the partner payment page	Enum
titanOrderId	The unique Titan order ID against which the domain is provisioned	The titanOrderId is used to identify the order being referenced	Enum
domainName	Customer Domain being provisioned	The order provisioned in Titanmail is against the domainName provided by the partner within the API	Alphanumeric - upto 64 characters
customerId	The customer ID stored on your end for each customer	This is used to identify all the orders linked to a particular customer	Alphanumeric - upto 64 characters
planType	Current Titan plan type configured for the customer	This is used to identify the existing Titan plan for the customer and show relevant upgrade options to the customer on Partner end	Enum
noOfAccounts	The current number of accounts or mailboxes configured for the customer	This can be used by Partner to identify the current number of email accounts for the customer and allow the customer to upgrade the accounts accordingly	Integer
expiryDate	Date on which the existing package is set to expire	Titan assigns the expiry date in its systems based on this parameter	YYYY-MM-DD

CONTENT_DIMENSION_DID_UPDATE

Usage

Container websites may show content outside iframe and adjust iframe dimensions to align iframe and other views properly. For eg. To render some content just below the iframe, within the container website control panel. (an FAQ box, an NPS survey, a promotion banner etc)
Trigger

Event posted whenever the control panel content's height or width is updated by new content.

Example:

json

{
    "event": "CONTENT_DIMENSION_DID_UPDATE",
    "data": {
        "height": <val>,
        "width": <val>,
    }
}

Parameters Description:
- height : maximum height of current content inside control panel
- width: current width of control panel iframe
Note

However if the user changes the control panel dimension from outside interaction, such as dragging the width of the iframe to increase / decrease (if any such option is given by partners), then the partner panel window, first need to send postMessage Info to iframe with the below sample format:

Sample format:
js
```
// Trigger when iframe's width is changed by user externally //
iframeElement.contentWindow.postMessage({
    event: "IFRAME_WIDTH_DID_UPDATE",
    iframeWindowWidth: 80 + "vw" // Sample width after change
    }, '*');
    iframeElement.style.width =
    new_iframe_width // set new iframe width here
})
```
After listening to the IFRAME_WIDTH_DID_UPDATE event, the iframe window will trigger the event CONTENT_DIMENSION_DID_UPDATE with the format specified above.

LOADER_DID_APPEAR

Usage

Container websites may choose to hide content outside the iframe while the iframe page loads. For eg. the FAQ box outside the iframe can be hidden while the user is navigating between pages within the iframe.
Trigger

Event posted whenever new content fetching in the control panel is in progress, a loader is shown. If the partner panel wants to listen/show some UI only when the iframe is fully loaded, they can use this event to disable the interactions till the page is loaded. Partner can rely on other events 'PAGE_DID_LOAD' or 'CONTENT_DIMENSION_DID_UPDATE' to take action when the loader is hidden.

Example:

window.addEventListener("message", (event) =>
    {
        const eventName = event.data.event;
        if (eventName === LOADER_DID_APPEAR) {
        //here partner panel can decide to hide some sections until iframe is fully loaded e.g not showing FAQ section
    })

EMAIL_ACCOUNTS_CHANGED

Usage

The container websites might need to dynamically update the number of purchased/active email accounts. They can do so by adding a listener to this event.

Format of the event:

json

{
    "event": "EMAIL_ACCOUNTS_CHANGED",
    "data": {
        "active": <val>,
        "purchased": <val>,
        "limit": <val>
    }
}

Example Usage:

javascript

window.addEventListener('message', function(event) {
    const eventData = event.data;
    const eventName = eventData.event;
    if (eventName === "EMAIL_ACCOUNTS_CHANGED") {
        const mailboxData = eventData.data;
        console.log("The number of active email accounts in use are: ", mailboxData.active);
        console.log("The number of total purchased email accounts are: ", mailboxData.purchased);
        console.log("The number of limit to email accounts are: ", mailboxData.limit);
    }
});

Trigger

Whenever there is a change in the number of purchased/active mailboxes, Titan makes an API call from its Frontend. If Titan detects any changes in the number of accounts, active or purchased, Titan will send this event as a postMessage.

Titan Event Notification

#On Mail Order creation at Titan

#On Mail Order status update at Titan

#On Mail Order data purge at Titan

#On Mail Order Upgrade/Renew at Titan

#On Mail Order Transfer at Titan

#On Mail Order Setup Completed at Titan

#On Mail Customer Update at Titan

#On Email Account creation or modification at Titan

#On Email Account status update at Titan

#On Email Account data purge at Titan

#On Internal Forwarding Account creation at Titan

#On Internal Forwarding Account deletion at Titan

#Titan Control Panel iframe events

#Message structure in titan control panel

#Events Handling in partner panel

#Events list

On Mail Order creation at Titan

On Mail Order status update at Titan

On Mail Order data purge at Titan

On Mail Order Upgrade/Renew at Titan

On Mail Order Transfer at Titan

On Mail Order Setup Completed at Titan

On Mail Customer Update at Titan

On Email Account creation or modification at Titan

On Email Account status update at Titan

On Email Account data purge at Titan

On Internal Forwarding Account creation at Titan

On Internal Forwarding Account deletion at Titan

Titan Control Panel iframe events

Message structure in titan control panel

Events Handling in partner panel

Events list