Titan API Document (1.0.0)

All API requests must be over https. All API request/response bodies are formatted as JSON.

US Region

• API Base URL: https://bll.titan.email
• Control Panel URL: https://manage.titan.email

EU Region

• API Base URL: https://api-euc1.titan.email/bll
• Control Panel URL: https://manage-euc1.titan.email

• To Authorize API requests, an Authorization header described below must be added to all requests.
• We will share an API Key, which must be added to the Authorization header for us to identify the source of the request.
• This API Key is a shared secret key between Partner and Titan.
• Generally, for any API calls we make to your servers you must validate that the same contains this Authorization header and a valid API Key.
• Partners should whitelist following Titan IPs - 3.92.40.244, 34.197.244.225, 52.7.187.26 & 3.64.226.220
• It is recommended that partners should provide IPs of their servers to Titan so that Titan can do IP whitelisting for APIs present in this doc.

Sample Header

POST https://bll.titan.email/<API_ROUTE> HTTP/1.1
Authorization: API.Key

API.Key will be provided by us during onboarding

Example:

Assume we share an **API.Key** with you: 123456abcdefgh-

Appropriate Header syntax -
POST https://bll.titan.email/partner/createMailOrder HTTP/1.1
Authorization: 123456abcdefgh-

• Sample Error Response

  {
      "desc":"No Active domain found",
      "error":"DomainNotFound",
      "statusCode":404,
      "reqID":"4605e6ef-ea50-4a81-83f6-06159a9a906b"
  }
  

• error
  • In case of an error, the server will send a well-defined error response as given below. The API consumers can take a decision regarding the message to be shown based on the error.
  • e.g : PartnerNotFound, DomainNotFound, UserNotFound, BAD_REQUEST, EXTERNAL_ERROR etc.
    • PartnerNotFound - Partner does not exist (or is marked inactive) in titan infra.
    • UserNotFound - Customer does not exist in titan infra.
    • DomainNotFound - Domain does not exist (or is marked inactive, in certain cases) in titan infra.
    • AccountNotFound - Email account does not exist (or is marked inactive, in certain cases) in titan infra.
    • FORBIDDEN - Unauthorized Access: Non-Whitelisted Ip
    • UNAUTHENTICATED - No auth header found
  • If we have messed up, you may get an INTERNAL_SERVER_ERROR. In such cases, please forward api call details to your Titan PoC.
• statusCode is standard Http Error Codes. e.g : 404, 401, 500 etc.
• desc is verbose error description.
• Every api in the doc there is a section for possible error codes.

• <domain name> mx1.titan.email | mx2.titan.email
• <domain name> TXT v=spf1 include:spf.titan.email ~all
• _dmarc.<domain name> TXT v=DMARC1;p=none;sp=none;adkim=r;aspf=r;pct=100 (Optional)

• In case of an HTTP 5XX or a timeout please retry the API call
• For each retry wait for 2X the number of seconds of the previous retry until you get an HTTP 200 OK
• For e.g. retry after 1s, 2s, 4s, 8s, 16s, 32s, 64s ... and so on
• You may stop retrying after 24 hours and log the same on your side
• Parties must notify one another if we continue to get an error or a timeout for greater than 1 hour

All APIs, unless specified, are idempotent, hence they can safely be called multiple times.

Below URLs are to be used in the request headers to call the APIs in the staging or production environments

APIs for creation and management of mail Orders on the Titan Cloud infrastructure

All Redirection between Partner website to Titanmail control panel and from Titanmail control panel to Partner website will contain JWT signature for authentication and authorization of data exchanged. Note - For further information on JSON Web Tokens (JWT) - Click here

Titan mail will provide you one shared API Key which will be used for all API authentication and Hash computation.

    Header
    {
    "typ": "JWT",
    "alg": "HS256"
    }

Currently Titanmail supports only the HS256 algorithm.

Construct JWT_TOKEN using the above header and payload specific to each redirect request.

Autologin Titan user into webmail

To auto login the Titan user into webmail, redirect to Titan webmail with these query params:

• webmailAutoLoginToken as slt (You will receive this token in the response whenever you create an email account)
• created email as email_account
• true as clearSession (This is optional. Add parameter in case the expectation is to log out any existing logged in accounts on webmail)

Example: https://app.titan.email/?slt=1:nkLjBJX9Uqgy&email_account=james@xyz.com

Note: webmailAutoLoginToken is a short lived token which is meant to be used immediately in the flow after creating an email account. This token should not be persisted and can't be used later to auto login into webmail.

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, we will reattempt to push a notification once every minute until we receive 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

    {
        "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

    {
        "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.

    {
        "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

    {
        "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

    {
        "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"
            }
        }
    }

On Mail Order Setup Completed at Titan

This is triggered when domain setup has completed.

    {
        "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.

    {
        "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

    {
        "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>",
            "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

    {
        "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",
            "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.

    {
        "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",
        }
    }

On Internal Forwarding Account creation at Titan

Note :

• recipients is optional fields

    {
        "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>",
            "recipients": [
              "email1@xyz.com",
              "email2@xyz.com"
            ]
        }
    }

On Internal Forwarding Account deletion at Titan

    {
        "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>"
        }
    }

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:

  {
    "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:

  {
    "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:

  {
    "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	We assign the expiry date in our 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:

  {
      "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:

  // 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:

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

  Example Usage:

  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, we make an API call from our Frontend. If we detect any changes in the number of accounts, active or purchased, we will send this event as a postMessage.