{ "openapi": "3.0.3", "info": { "title": "Titan API Document", "version": "1.0.0", "description": "## Introduction\n\nAll API requests must be over https.\nAll API request/response bodies are formatted as JSON.\n\n## Base URLs\n\n### US Region\n\n- API Base URL: https://bll.titan.email\n- Control Panel URL: https://manage.titan.email\n\n### EU Region\n\n- API Base URL: https://api-euc1.titan.email/bll\n- Control Panel URL: https://manage-euc1.titan.email\n\n## Authentication\n\n### Calls from you to Titan\n\n- Send your API key in the **Authorization** header of every request. Titan gives you the API key during onboarding. Only you and Titan know it.\n- **IP whitelist (recommended):** Give Titan the IP addresses of the servers that call the Titan APIs. You can give single IPv4 or IPv6 addresses, or ranges in CIDR format (for example `203.0.113.0/24`). Titan then processes only the calls from these addresses. A call from any other address gets `FORBIDDEN` (403). If you give no addresses, Titan processes calls from all addresses.\n\n#### Sample Header\n```\nPOST https://bll.titan.email/ HTTP/1.1\nAuthorization: API.Key\n\nTitan gives the API.Key to the partner during onboarding.\n\nExample: Titan gives the partner this API.Key: 123456abcdefgh-\nThe header is then:\nPOST https://bll.titan.email/partner/createMailOrder HTTP/1.1\nAuthorization: 123456abcdefgh-\n```\n\n### Calls from Titan to you (webhooks)\n\n- Titan sends the same API key in the **Authorization** header of each call to your servers. Before you process a call, make sure that it has a valid API key.\n- Whitelist these Titan IP addresses: 3.92.40.244, 34.197.244.225, 52.7.187.26 and 3.64.226.220.\n\n## General Errors\n\nMost errors have this body:\n\n```json\n{\n \"desc\":\"No Active domain found\",\n \"error\":\"DomainNotFound\",\n \"statusCode\":404,\n \"reqID\":\"4605e6ef-ea50-4a81-83f6-06159a9a906b\"\n}\n```\n\n- `error` is the error code: a fixed name that identifies the error, for example `DomainNotFound`. Use it in your code to handle each error.\n- `statusCode` is the HTTP status code, for example 404, 401 or 500.\n- `desc` is the error description.\n- `reqID` is the ID of the request. Send it to Titan when you report a problem.\n\nThese errors are common to many APIs:\n\n| error | HTTP | Cause | What to do |\n|---|---|---|---|\n| `UNAUTHENTICATED` | 401 | The request has no Authorization header. | Send your API key in the Authorization header. |\n| `NOT_FOUND` | 404 | The API key is not correct, or it is disabled. | Send the API key that Titan gave you. |\n| `FORBIDDEN` | 403 | The request comes from an IP address that is not on your whitelist. | Send the request from a whitelisted IP address, or ask Titan to add the address. |\n| `BAD_REQUEST` | 400 | The request body is not valid JSON. | Correct the body. |\n| `DomainNotFound` | 404 | No mail order matches the titanOrderId, or the domainName and customerId, that you sent. Some APIs also return this error for a deleted order. | Check the values. To find an order, use [listMailOrders](#operation/listMailOrders). |\n| `UserNotFound` | 404 | No customer matches the customerId that you sent. | Check the customerId. |\n| `AccountNotFound` | 404 | No email account matches the titanAccountId, or the email, that you sent. With an email, a deleted account also gives this error. | Check the values. To find an account, use [listEmailAccounts](#operation/listEmailAccounts). |\n| `TooManyRequests` | 429 | The IP address sent more requests than the rate limit. | Wait, then send the request again with exponential back-off. See [Recommended API Retry logic](#section/Recommended-API-Retry-logic:-Exponential-Back-off). |\n| `InternalServerError` | 500 | A problem occurred at Titan. | Retry with exponential back-off. If the error continues, send the reqID to your Titan PoC. |\n\nEach API lists only its own errors.\n\n## DNS Records to be added to provision order on Titan\n\nAdd these records to the DNS of the domain. Use the values of your region (see Base URLs).\n\n### MX\n\n| Host | Type | Priority | US value | EU value |\n|---|---|---|---|---|\n| `` | MX | 10 | mx1.titan.email | mx0101.titan.email |\n| `` | MX | 20 | mx2.titan.email | mx0102.titan.email |\n\n- Remove all other MX records of the domain. If the domain has an MX record that points to a different server, the MX check fails.\n\n### SPF\n\n| Host | Type | US value | EU value |\n|---|---|---|---|\n| `` | TXT | `v=spf1 include:spf.titan.email ~all` | `v=spf1 include:spf0101.titan.email ~all` |\n\n- A domain can have only one SPF record (a TXT record that starts with `v=spf1`).\n- If the domain already has an SPF record, do not add a second one. Add the Titan include to the record that you have. For example: `v=spf1 include:_spf.example.net include:spf.titan.email ~all`.\n\n### DKIM\n\n1. Call [generateDKIMKeys](#operation/generateDKIMKeys) for the order.\n2. Add a TXT record with the values from the response:\n\n| Host | Type | Value |\n|---|---|---|\n| `._domainkey.` | TXT | the `txtRecord` from the response |\n\n- Use the `selector` from the response.\n- Titan checks the DKIM record every hour for 10 hours after the first call.\n\n### DMARC (Optional)\n\n| Host | Type | Value |\n|---|---|---|\n| `_dmarc.` | TXT | `v=DMARC1;p=none;sp=none;adkim=r;aspf=r;pct=100` |\n\n### Check the records\n\n- [dnsLookup](#operation/dnsLookup) shows the MX and SPF records of the domain, and if they are correct (`mxVerified`, `spfVerified`).\n\n## Recommended API Retry logic: Exponential Back off\n- In case of an HTTP 429, 5XX or a timeout please retry the API call\n- For each retry wait for 2X the number of seconds of the previous retry until you get an HTTP 200 OK\n- For e.g. retry after 1s, 2s, 4s, 8s, 16s, 32s, 64s ... and so on\n- You may stop retrying after 24 hours and log the same on your side\n- Titan and the partner must tell each other if errors or time-outs continue for more than 1 hour\n\n### Rate limits\n\n- Send a maximum of 500 requests per minute to each API from one IP address. Titan can change this limit.\n- When you pass the limit, Titan returns HTTP `429`:\n ```json\n {\n \"error\":\"TooManyRequests\",\n \"desc\":\"Too many requests\",\n \"statusCode\":429\n }\n ```\n- When you get `429`, wait, then send the request again with the back-off above. Do not send many requests in parallel.\n\n## APIs exposed by Titan\n\nAll APIs, unless specified, are idempotent, hence they can safely be called multiple times.\n\nBelow URLs are to be used in the request headers to call the APIs in the staging or production environments
\n" }, "servers": [ { "url": "https://bll.titan.email", "description": "US Region" }, { "url": "https://api-euc1.titan.email/bll", "description": "EU Region" } ], "tags": [ { "name": "General APIs" }, { "name": "Mail Order Management APIs", "description": "APIs for creation and management of mail Orders on the Titan Cloud infrastructure" }, { "name": "Mail Customer APIs" }, { "name": "Catch-all Management APIs" }, { "name": "Redirection between Partner and Titan", "description": "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.\nNote - For further information on JSON Web Tokens (JWT) - [Click here](https://jwt.io/introduction/)\n\nTitan mail will provide you one shared API Key which will be used for all API authentication and Hash computation.\n```\n Header\n {\n \"typ\": \"JWT\",\n \"alg\": \"HS256\"\n }\n```\n\nCurrently Titanmail supports only the HS256 algorithm.\n\nConstruct JWT_TOKEN using the above header and payload specific to each redirect request.\n\n### Autologin Titan user into webmail\n\nTo auto login the Titan user into [webmail](https://app.titan.email/), redirect to Titan webmail with these query params:\n- webmailAutoLoginToken as **slt** (You will receive this token in the response whenever you create an email account)\n- created email as **email_account**\n- true as **clearSession** (This is optional. Add parameter in case the expectation is to log out any existing logged in accounts on [webmail](https://app.titan.email/))\n\nExample: https://app.titan.email/?slt=1:nkLjBJX9Uqgy&email_account=james@xyz.com\n\nNote: 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](https://app.titan.email/).\n" }, { "name": "Titan Event Notification", "description": "These are the webhooks configured for event notification between from the Titan cloud infrastructure to the partner.\n\nThere will be webhooks provided to the Partner for notifications of changes occurring on Titan’s end.\nAll 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 -\n* The Partner Key will be sent in the **Authorization** header of all the requests.\n* Source IPs will be shared with the Partner during deployment\n\n**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.\n\nTitan will notify partners on various life cycle events of a Mail Order or an Email Account.\n\n### On Mail Order creation at Titan\n\n**Note**:\n\n- noOfAccounts represents the total number of accounts a user has purchased.\n- customerName, customerEmailAddress, customerCountry, billingCycle are optional fields\n\n``` json\n\n {\n \"id\": \"\",\n \"event\": \"MAIL_ORDER_CREATED\",\n \"data\":{\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"customerName\": \"customer name\",\n \"customerEmailAddress\": \"customer email address\",\n \"customerCountry\": \"< 2 letter ISO CODE, e.g. US>\",\n \"planType\": \"\",\n \"expiryDate\": \"\",\n \"storageLimit\": \"\",\n \"noOfAccounts\": \"\",\n \"billingCycle\": \"monthly\",\n \"status\": \"active|pending\",\n \"metadata\": {\n \"cpanelHostName\": \"\",\n \"cpanelUserName\": \"\"\n }\n }\n }\n```\n\n### On Mail Order status update at Titan\n\n**Note** :\n\n- type - type of the suspension like abuse, expiry, employee left\n- If a domain is suspended with some suspension type then it can only be unblocked by that type only.\n- suspenderRole - The entity that suspended the email account. It can have following values\n - titan\n - titanSupport\n - partner\n - partnerSupport\n - domainAdmin - The email account admin that is part of only this domain\n - accountAdmin - The Person that get the domain provisioned in the Titan\n - account - the email account holder person\n- suspenderRole have precedence in following order\n - (titan , titanSupport) > (partner, partnerSupport) > (domainAdmin, accountAdmin) > account\n- The higher precedence member can remove the lower precedence member suspension\n- suspendedOn - suspension date in YYYY-MM-DD format\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"MAIL_ORDER_STATUS_UPDATED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"oldStatus\": \"active | pending | suspended | deleted\",\n \"newStatus\": \"active | suspended | deleted\",\n \"suspensions\": [\n {\n \"type\": \"abuse\",\n \"suspenderRole\": \"titanSupport\",\n \"suspendedOn\": \"2021-01-13\"\n }\n ]\n }\n }\n```\n\n### On Mail Order data purge at Titan\n\n**Note** :\n- This event will be fired once the mail-order data has been purged. This happens 30 days post the deletion event.\n- This notification signifies that order data has been permanently deleted and cannot be re-activated.\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"MAIL_ORDER_PURGED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\"\n }\n }\n```\n\n### On Mail Order Upgrade/Renew at Titan\n\n**Note** :\n\n- Any other events can be added as per Partners requirements.\n- These events are only send when the billing is managed by Titan for the domain\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"< PLAN_UPGRADED | ACCOUNTS_PURCHASED | PLAN_RENEWED > \",\n \"data\": {\n \"titanOrderId\": 1,\n \"domainName\": \"example.com\",\n \"customerId\": \"abc\",\n \"configBeforeUpdate\": {\n \"planType\": \"\",\n \"expiryDate\": \"\",\n \"storageLimitInMB\": \"\",\n \"noOfAccounts\": \"\",\n \"billingCycle\": \"monthly\"\n },\n \"configAfterUpdate\": {\n \"planType\": \"\",\n \"expiryDate\": \"\",\n \"storageLimitInMB\": \"\",\n \"noOfAccounts\": \"\",\n \"billingCycle\": \"monthly\"\n },\n \"paymentDetails\": {\n \"amount\": 10.5,\n \"currency\": \"USD\"\n }\n }\n }\n\n```\n\n### On Mail Order Transfer at Titan\n\n**Note** :\n\n- customerBeforeTransfer/customerAfterTransfer are present only when the domain's customer/owner changed as part of the transfer; they are omitted otherwise.\n- serverBeforeTransfer/serverAfterTransfer are present only when the hosting server changed as part of the transfer; they are omitted otherwise.\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"MAIL_ORDER_TRANSFERRED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer -- new owner of domain\",\n \"customerBeforeTransfer\": {\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"customerName\": \"customer name\",\n \"customerEmailAddress\": \"Email Address of customer\",\n \"customerCountry\": \"US\"\n },\n \"customerAfterTransfer\": {\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"customerName\": \"customer name\",\n \"customerEmailAddress\": \"Email Address of customer\",\n \"customerCountry\": \"IN\"\n },\n \"serverBeforeTransfer\": {\n \"titanServerId\": \"\",\n \"host\": \"\"\n },\n \"serverAfterTransfer\": {\n \"titanServerId\": \"\",\n \"host\": \"\"\n }\n }\n }\n```\n\n### On Mail Order Setup Completed at Titan\n\nThis is triggered when domain setup has completed.\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"MAIL_ORDER_SETUP_COMPLETED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"customerName\": \"customer name\",\n \"customerEmailAddress\": \"customer email address\",\n \"mailService\" : \"\",\n \"metadata\": {\n \"cpanelHostName\": \"\",\n \"cpanelUserName\": \"\"\n }\n }\n }\n```\n\n### On Mail Customer Update at Titan\n\nThis is triggered when mail customer `customerEmail`, `name` or `country` is updated.\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"MAIL_CUSTOMER_UPDATED\",\n \"data\": {\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"customerBeforeUpdate\": {\n \"customerName\": \"customer name\",\n \"customerEmailAddress\": \"Email Address of customer\",\n \"customerCountry\": \"US\"\n },\n \"customerAfterUpdate\": {\n \"customerName\": \"New customer name\",\n \"customerEmailAddress\": \"New Email Address of customer\",\n \"customerCountry\": \"IN\"\n }\n }\n }\n```\n\n### On Email Account creation or modification at Titan\n\n**Note** :\n\n- name, alternateEmailAddress are optional fields\n- For EMAIL_ACCOUNT_CREATED, isAdmin and aliases are also optional fields\n- titanAccountId is the Titan Mail generated unique ID for the email account\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"EMAIL_ACCOUNT_CREATED | EMAIL_ACCOUNT_MODIFIED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"email\": \"\",\n \"titanAccountId\": \"\",\n \"name\": \"Name of the user\",\n \"alternateEmailAddress\": \"Alternate Email for password reset mails\",\n \"isAdmin\": \"true/false\",\n \"aliases\": \"list of aliases of email account\"\n }\n }\n```\n\n### On Email Account status update at Titan\n\n**Note** :\n\n- type - type of the suspension like abuse, expiry, employee left\n- If an account is suspended with some custom suspension type then it can only be unblocked by that type only.\n- suspenderRole - The entity that suspended the email account. It can have following values\n - titan\n - titanSupport\n - partner\n - partnerSupport\n - domainAdmin - The email account admin that is part of only this domain\n - accountAdmin - The Person that get the domain provisioned in the Titan\n - account - the email account holder person\n- suspenderRole have precedence in following order\n - (titan , titanSupport) > (partner, partnerSupport) > (domainAdmin, accountAdmin) > account\n- The higher precedence member can remove the lower precedence member suspension\n- suspendedOn - suspension date in YYYY-MM-DD format\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"EMAIL_ACCOUNT_STATUS_UPDATED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"email\": \"abc@xyz.com\",\n \"titanAccountId\": \"\",\n \"oldStatus\": \"active | suspended | deleted\",\n \"newStatus\": \"active | suspended | deleted\",\n \"suspensions\": [\n {\n \"type\":\"abuse\",\n \"suspenderRole\":\"titanSupport\",\n \"suspendedOn\":\"2021-01-13\"\n }\n ]\n }\n }\n```\n\n### On Email Account data purge at Titan\n\n**Note** :\n\n- This event will be fired once the email-account data has been purged. This happens 30 days post the deletion event.\n- This notification signifies that email-account data has been permanently deleted and this email-account cannot be re-activated.\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"EMAIL_ACCOUNT_PURGED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"email\": \"abc@xyz.com\",\n \"titanAccountId\": \"\"\n }\n }\n```\n\n### On Internal Forwarding Account creation at Titan\n\n**Note** :\n\n- recipients is optional fields\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"INTERNAL_FORWARDING_ACCOUNT_CREATED | INTERNAL_FORWARDING_ACCOUNT_MODIFIED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"email\": \"\",\n \"titanAccountId\": \"\",\n \"recipients\": [\n \"email1@xyz.com\",\n \"email2@xyz.com\"\n ]\n }\n }\n```\n\n### On Internal Forwarding Account deletion at Titan\n\n``` json\n {\n \"id\": \"\",\n \"event\": \"INTERNAL_FORWARDING_ACCOUNT_DELETED\",\n \"data\": {\n \"titanOrderId\": \"\",\n \"domainName\": \"domain name\",\n \"customerId\": \"Unique customer Id on your side for this customer\",\n \"email\": \"\",\n \"titanAccountId\": \"\"\n }\n }\n```\n\n### Titan Control Panel iframe events\n\nTo consume the events posted to the container website via [window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) from the embedded Titan Control Panel.\n\n#### Message structure in titan control panel\n\n- Parameters Description:\n - event (string, required)\n - data (object, optional)\n- Sample format:\n ``` json\n {\n \"event\": \"\",\n \"data\": \"\"\n }\n ```\n\n#### Events Handling in partner panel\n\nUse [addEventListener()](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) method to set up a function to be called whenever a message is posted from the iframe to the partner panel.\n``` js\nwindow.addEventListener(\"message\", (event) => {\n if(event.data.event) {\n //Do needful action here//\n }\n}, false);\n```\n\n#### Events list\n\nThese are the standard events sent from Iframe Titan control panel to partner panel.\n\n**PAGE_DID_LOAD**\n\n- Usage\n\n 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.\n\n- Trigger\n\n 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.\n\n- Example:\n ``` json\n {\n \"event\": \"PAGE_DID_LOAD\",\n \"data\": {\n \"pageName\": \"\" /* Current path name */\n }\n }\n ```\n\n**PAYMENT_ACTION**\n\n- Usage\n\n 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.\n\n- Trigger\n\n Event posted whenever a user takes action related to payments eg: upgrading plan, buying more accounts, renew etc.\n\n- Example:\n ``` json\n {\n \"event\": \"PAYMENT_ACTION\",\n \"data\": {\n \"action\":\"upgradePlan|buyMoreAccounts|renewOrder|billing\",\n \"titanOrderId\": \"\",\n \"domainName\": \"example.com\",\n \"customerId\": \"\",\n \"planType\": \"free|pro|premium\",\n \"noOfAccounts\": \"\",\n \"expiryDate\": \"\"\n }\n }\n ```\n\n- Parameters Description\n\n | Parameters | Description | Purpose of the parameter | Data Type |\n |---|---|---|---|\n | 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 |\n | titanOrderId | The unique Titan order ID against which the domain is provisioned | The titanOrderId is used to identify the order being referenced | Enum |\n | 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 |\n | 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 |\n | 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 |\n | 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 |\n | 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 |\n\n**CONTENT_DIMENSION_DID_UPDATE**\n\n- Usage\n\n 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)\n\n- Trigger\n\n Event posted whenever the control panel content's height or width is updated by new content.\n\n- Example:\n ``` json\n {\n \"event\": \"CONTENT_DIMENSION_DID_UPDATE\",\n \"data\": {\n \"height\": ,\n \"width\": ,\n }\n }\n ```\n\n- Parameters Description:\n - height : maximum height of current content inside control panel\n - width: current width of control panel iframe\n\n- Note\n\n 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:\n\n Sample format:\n ``` js\n // Trigger when iframe's width is changed by user externally //\n iframeElement.contentWindow.postMessage({\n event: \"IFRAME_WIDTH_DID_UPDATE\",\n iframeWindowWidth: 80 + \"vw\" // Sample width after change\n }, '*');\n iframeElement.style.width =\n new_iframe_width // set new iframe width here\n })\n ```\n\n 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.\n\n**LOADER_DID_APPEAR**\n\n- Usage\n\n 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.\n\n- Trigger\n\n 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.\n\n- Example:\n ``` js\n window.addEventListener(\"message\", (event) =>\n {\n const eventName = event.data.event;\n if (eventName === LOADER_DID_APPEAR) {\n //here partner panel can decide to hide some sections until iframe is fully loaded e.g not showing FAQ section\n })\n ```\n\n**EMAIL_ACCOUNTS_CHANGED**\n\n- Usage\n\n 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.\n\n Format of the event:\n ```json\n {\n \"event\": \"EMAIL_ACCOUNTS_CHANGED\",\n \"data\": {\n \"active\": ,\n \"purchased\": ,\n \"limit\": \n }\n }\n ```\n\n Example Usage:\n ```javascript\n window.addEventListener('message', function(event) {\n const eventData = event.data;\n const eventName = eventData.event;\n if (eventName === \"EMAIL_ACCOUNTS_CHANGED\") {\n const mailboxData = eventData.data;\n console.log(\"The number of active email accounts in use are: \", mailboxData.active);\n console.log(\"The number of total purchased email accounts are: \", mailboxData.purchased);\n console.log(\"The number of limit to email accounts are: \", mailboxData.limit);\n }\n });\n ```\n\n- Trigger\n\n 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.\n" }, { "name": "Email Account Management APIs" }, { "name": "Internal Forwarding Accounts Management APIs" }, { "name": "Data Structures", "description": "### titanOrderId\n\n- titanOrderId: 1 (number, required)\n\n The unique order ID against each domain provisioned with Titan\n\n### domainName\n\n- domainName: xyz.com (string)\n\n domain name\n\n### customerId\n\n- customerId: qwe123 (string)\n\n customer id\n\n### planType\n\n- planType: pro (enum)\n\n This is the Titan mail plan. This would vary based on the plans being positioned with the partner.\n\n Members: free, pro, premium, pro_trial, premium_trial, ultra, ultra_trial\n\n### status\n\n- status: active (enum)\n\n Members: active, pending, suspended, deleted\n\n### titanAccountId\n\n- titanAccountId: 1 (number, required)\n\n The unique mail account ID against each email provisioned with Titan\n\n### titanResellerId\n\n- titanResellerId: 1 (number, required)\n\n The unique reseller ID generated by Titan for each reseller created by a partner\n\n### EmptyResponse\n\n- reqID: server.req.id (string, required)\n" } ], "paths": { "/partner/healthCheck": { "get": { "operationId": "healthCheck", "summary": "Health Check API", "description": "API to check Titan API's Gateway health. The approximate interval, between health checks should be at least 1 minute.\nIf this API fails more than 3 times consecutively than partner should inform Titan.\n\n**Note**:\n- Dashboard to check [Titan Mailing infra's health.](https://status.titan.email/)", "tags": [ "General APIs" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/createMailOrder": { "post": { "operationId": "createMailOrder", "summary": "Create Mail Order", "description": "API to provision a Mail Order on Titan.\n\n**Notes** :\n- A welcome email with Titan Control Panel login and set‑password details is sent to customerEmailAddress. To skip it on a specific order, pass sendWelcomeEmail: false. To disable it permanently for your account, contact Titan support.\n", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domainName", "customerId", "planType" ], "properties": { "domainName": { "type": "string", "example": "xyz.com", "description": "Customer mail order being provisioned\nThe order provisioned in Titanmail is against the domainName provided by the partner within the API" }, "orderId": { "type": "string", "example": "12431", "description": "The order ID stored on your end for this mail order, if any. If needed, You can use this data to correlate orders at your end and in Titan.The data is returned in [listMailOrders](#operation/listMailOrders) call." }, "customerId": { "type": "string", "example": "abcd123", "description": "The customer ID stored on your end for each customer\nThis is used to identify all the orders linked to a particular customer" }, "customerName": { "type": "string", "example": "Adam Smith", "description": "Name of the customer as stored in the partner's system. It is recommended to send the full name as Titan utilizes this for any communication sent across to the customer." }, "customerEmailAddress": { "type": "string", "example": "adam@gmail.com", "description": "The email address with which the customer registers on the partner website\nThis email is used in order for Titan to send out the password setup email or any signup/usage nudges to get the customer to utilize the email\nThis email will be used by the customer to login into [Control Panel](https://manage.titan.email). This user will also be the primary admin for the domain" }, "alternateEmailAddress": { "type": "string", "example": "abc@xyz.com", "description": "This email will be used to send emails, in case email delivery fails for customerEmailAddress" }, "password": { "type": "string", "example": "asdfqwe", "description": "Password for signing into Domain [Control Panel](https://manage.titan.email)" }, "customerCountry": { "type": "string", "example": "US", "description": "Should be the 2 letter ISO Code, country from which the customer is accessing partner website/making the purchase.\nTitan will use this to identify the localized pricing based on the location of the customer in cases where Titan mail is managing the billing." }, "planType": { "type": "string", "example": "pro", "enum": [ "free", "pro", "premium", "pro_trial", "premium_trial", "ultra", "ultra_trial" ], "description": "This is the Titan mail plan to be provisioned for the provided mail order. This would vary based on the plans being positioned with the partner. It is highly recommended to provide payment details in case this is a paid plan" }, "noOfAccounts": { "type": "number", "example": 10, "description": "Required for Paid Plans\nThe number of accounts or mailboxes to be provisioned against the domain.\nThis is used as a limiting parameter for the user to create accounts within the [Control Panel](https://manage.titan.email). E.g. if this is set to 2, the user will not be allowed to create more than 2 mailboxes" }, "titanResellerId": { "type": "number", "example": 456, "description": "Titan Reseller ID for reseller-level branding. If provided, the order will use the branding associated with this reseller.\nIf null, falls back to partner's default branding." }, "expiryDate": { "type": "string", "example": "2020-02-20", "description": "In `yyyy-MM-dd` format.
\nRequired for Paid and Trial Plans.
\nIf the billing is managed by partner then partner should mark mail order suspended on expiry date. Titan does not suspend, expire, or delete the mail order on your behalf in this mode, except as a safety-net measure: Titan may suspend a mail order whose expiryDate has remained stale for an extended period with no partner action.
\nIf the billing is managed by Titan, then Titan will mark mail order suspended on non-renewal on expiry day. And after 7 days of expiry, mail order will be marked deleted. The permanent deletion of mail order data happens after 30 days of deletion." }, "paymentTxnId": { "type": "string", "example": "qweradsf", "description": "Partner should provide transactionId when the order is provisioned on paid plan or associated order is paid" }, "chargedAmount": { "type": "number", "example": 1.1, "description": "Required for Paid Plans\nTotal amount charged by the partner to the end customer in the customer's currency for this purchase including taxAmount. It is the actual cost that the user has paid while purchasing the order after any discount (which also includes tax if any). Precision upto 2 decimal places.\nUsed primarily for reference and reporting on Titan's end. This is applicable only in the case of a paid plan.\nFor free/trial plans, this should be passed as \"0\"" }, "currency": { "type": "string", "example": "USD", "description": "Should be 3 letter ISO code\nThis is the currency in which the customer is being charged for Titan mail. Default USD (can be changed as for partner) . Used primarily for reference and reporting on Titan's end." }, "chargedUSDAmount": { "type": "number", "example": 1.1, "description": "Total amount charged by the partner to the end customer in USD for this purchase including taxAmount. It is the actual cost that the user has paid in USD while purchasing the order after any discount (which also includes tax if any). Partner should provide this value, if the order is provisioned on paid plan. Open exchange rates will be used if the partner does not provide this value." }, "discountAmount": { "type": "number", "example": 0.1, "description": "Any ad hoc discount given to the customer for this purchase. This should be passed in the original currency in which amount was charged to the customers. This field is just for book-keeping. Titan will use this as a placeholder to check if there are any discounts given to the customer." }, "taxAmount": { "type": "number", "example": 0.1, "description": "Amount collected from the user as TAX amount in the customer's currency for this purchase. Titan will deduct this amount from the chargedAmount to get revenue sharing amount. Precision upto 2 decimal places." }, "billingCycle": { "type": "string", "example": "monthly", "enum": [ "monthly", "quarterly", "semesterly", "yearly", "two_yearly", "three_yearly", "four_yearly", "five_yearly" ], "description": "This defines the period for which the customer has been billed for Titan mail by the partner.\nThis is for Titan to track the billing cycle/details for that customer. Existing options are" }, "locale": { "type": "string", "example": "en-gb", "description": "Specifies the language to be set within the Email Control Panel.\nList of support Titan languages - [link](https://docs.google.com/document/d/16ZHxYOmp1GpWm_oEWMMvSXEX-BcCj0B06vR1qrL-_yM/edit)\nDefault is set to en-us" }, "source": { "type": "string", "example": "hosting", "enum": [ "domain", "standalone", "hosting", "migrated" ], "description": "The source from which the order is received - Refers to the kind of package provisioned on the partners end.\nSource field should be either of these values - **domain, standalone, hosting, migrated**. It will be validated against these values when the Api call is made" }, "sourceContext": { "type": "string", "example": "website", "description": "The purchase hook from where Titan plan has been purchased by the customer \n_Purpose_ - This is used by Titan for reference and analyse the efficacy of various purchase hooks within the partner ecosystem from where customers are purchasing Titan paid plans. Some examples for sourceContext can be \"website\", \"hpanel_store\", \"cPanel_hosting_email_section\", \"cPanel_email_tab\", \"email_marketing\", etc." }, "metadata": { "type": "object", "description": "Details of associated partner order", "properties": { "associatedOrderExpiryDate": { "type": "string", "description": "Expiry date of the associated package/service sold by the partner. Stored as metadata on Titan's end. Used primarily for reference. Only applicable for bundled purchases" }, "associatedOrderPlanType": { "type": "string", "description": "The type of the plan of the associated order sold on the partners end. E.g. Shared Hosting plans as Small, Medium, Large etc. Stored as metadata on Titan's end. Used primarily for reference. Only applicable for bundled purchases" }, "cpanelHostName": { "type": "string", "description": "cPanel hostname where the user's hosting order has been provisioned/ Applicable only for hosting bundled Titan plans. Used at Titan's end to create mapping against appropriate cPanel server to provide user additional functionality inside cPanel. Only applicable for hosting bundled purchases. Enter the hostname, even if the hosting server is non-cPanel" }, "cpanelUserName": { "type": "string", "description": "cPanel username associated with this user's account. Applicable only for hosting bundled Titan plans. Used at Titan's end to create mapping against appropriate cPanel user account to provide user additional functionality inside cPanel. Only applicable for hosting bundled purchases. Enter the UserName, even if the hosting server is non-cPanel" }, "partnerBrand": { "type": "string", "description": "partner brand using which order creation happened" }, "paymentMethod": { "type": "string", "description": "payment method used during purchase, i.e : credit_card, paypal, etc" }, "autoRenew": { "type": "string", "description": "true/false, auto-renew value" } } }, "firstEmailAccount": { "type": "object", "description": "The first email account that partner wants to create with mail order. email & password both are required for first email account creation. This email will be marked admin by default.\n_Purpose_ - To allow partners provision first emailAccount along with order in 1 API call", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "example": "james@xyz.com", "description": "emailAddress of the email account to be created" }, "password": { "type": "string", "example": "password", "description": "password of the email account to be created, password should be at least 6 characters long" }, "isAdmin": { "type": "boolean", "example": true, "description": "Set true if emailAccount holder is admin. Default value of this field is true." }, "name": { "type": "string", "example": "James", "description": "Name of the email account holder" }, "firstName": { "type": "string", "example": "James", "description": "The first name of the customer for whom the email address is being created." }, "lastName": { "type": "string", "example": "Bond", "description": "The last name of the customer for whom the email address is being created." }, "alternateEmail": { "type": "string", "example": "james@gmail.com", "description": "alternate email for this mail account, reset password tokens are sent to alternate email" }, "metadata": { "type": "object", "description": "Additional metadata for capturing information of account", "properties": { "isFree": { "type": "boolean", "example": true, "description": "Specifies whether the account is free or not" } } } } }, "sendWelcomeEmail": { "type": "boolean", "example": true, "description": "Specifies whether or not to send email to customer for this newly created order.\nDefault value of this flag is true" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID", "titanOrderId" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" }, "titanOrderId": { "type": "number", "example": 1 }, "status": { "type": "string", "example": "active", "enum": [ "active", "pending", "suspended", "deleted" ], "description": "- pending: when another domain already exists in active state, for current domain Titan provisions in this 'pending' state. Pending domain is activated when current active domain is deleted from Titan infra." }, "firstEmailAccountDetails": { "type": "object", "description": "", "properties": { "webmailAutoLoginToken": { "type": "string", "description": "This token can be used to auto login into [titan webmail](https://app.titan.email/) , token validity is 1 hour. [Check here to see How to use this token](#webmailAutoLoginTokenUsage)" }, "titanAccountId": { "type": "number", "example": 1, "description": "unique account id at Titan's end." } } } } } } } }, "400": { "description": "BAD_REQUEST\n- domain for email of firstEmailAccount does not match.\n- Domain already exists with different details. happens multiple api calls, but with different data values.\n- On multiple requests, if the data is same then, Titan returns success response with domain status and firstAccount details.\n- If the firstEmail details is present in second api call and email is not created, then Titan creates the firstEmail with provided details and return webmail token." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/modifyMailOrder": { "post": { "operationId": "modifyMailOrder", "summary": "Modify Mail Order", "description": "API to modify an existing Mail Order on Titan", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" }, "orderId": { "type": "string", "example": "partner.order.id", "description": "The order ID stored on your end for this mail order, if any. If needed, You can use this data to correlate orders at your end and in Titan.The data is returned in [listMailOrders](#operation/listMailOrders) call. " }, "planType": { "type": "string", "example": "pro", "enum": [ "pro", "pro_trial", "premium", "premium_trial", "ultra", "ultra_trial" ], "description": "This is the Titan mail plan to be provisioned against the domain. In case the plan needs to be changed, the updated plan must be provided" }, "paymentTxnId": { "type": "string", "example": "qweradsf" }, "chargedAmount": { "type": "number", "example": 1.1, "description": "Required if domain is moving to paid plan or will remain on paid plan. This needs to be passed in customer's currency. It is the actual cost that the user has paid while purchasing the order after any discount (which also includes tax if any)." }, "chargedUSDAmount": { "type": "number", "example": 1.1, "description": "Total amount charged by the partner to the end customer in USD for this purchase including taxAmount. It is the actual cost that the user has paid in USD while purchasing after any discount (which also includes tax if any). Partner should provide this value, if the order is provisioned on paid plan. Open exchange rates will be used if the partner does not provide this value." }, "discountAmount": { "type": "number", "example": 0.1, "description": "Any ad hoc discount given to the customer for this purchase. This should be passed in the original currency in which amount was charged to the customers. Titan will use this as a placeholder to check if there are any discounts given to the customer." }, "taxAmount": { "type": "number", "example": 0.1, "description": "Amount collected from the user as TAX amount in the customer's currency for this purchase. Titan will deduct this amount from the chargedAmount to get revenue sharing amount. Precision upto 2 decimal places." }, "billingCycle": { "type": "string", "example": "monthly", "enum": [ "monthly", "quarterly", "semesterly", "yearly", "two_yearly", "four_yearly" ], "description": "This defines the period for which the customer has been billed for Titan mail by the partner.\nThis is for Titan to track the billing cycle/details for that customer. Existing options are" }, "expiryDate": { "type": "string", "example": "2020-02-20", "description": "In `yyyy-MM-dd` format.
\nRequired for Paid and Trial Plans.
\nIf the billing is managed by partner then partner should mark order suspended on expiry date. Titan does not suspend, expire, or delete the order on your behalf in this mode, except as a safety-net measure: Titan may suspend an order whose expiryDate has remained stale for an extended period with no partner action.
\nIf the billing is managed by Titan, then Titan will mark order suspended on non-renewal on expiry day. \nAnd after 7 days of expiry, order will be marked deleted. The permanent deletion of order data happens after 30 days of deletion.
\nIf order is on the free plan or moving to free plan and partner wants to reset expiry date to empty, then partner should send \"\" (empty string) as expiry date.
" }, "currency": { "type": "string", "example": "USD" }, "noOfAccounts": { "type": "number", "example": 10, "description": "The number of accounts or mailboxes to be provisioned after modification. E.g. User had 3 mailboxes and wants to buy 2 more, this parameter will have to be 2+3->5.\nThis is used as a limiting parameter for the user to create accounts within the control panel. E.g. if this is set to 5, the user will not be allowed to create more than 5 mailboxes" }, "action": { "type": "string", "enum": [ "newPurchase", "upgradeOrder", "addAccounts", "reduceAccounts", "renewOrder", "supportLedUpgrade", "supportLedExtension", "associatedOrderUpgrade", "associatedOrderRenew", "orderSetup", "downgradeOrder", "upgradeAndAddAccounts", "renewAndAddAccounts", "renewAndUpgrade" ], "description": "Description for the type of modifications being performed" }, "source": { "type": "string", "enum": [ "domain", "standalone", "hosting", "migrated" ], "description": "The source from which the order is received - Refers to the kind of package provisioned on the partners end.\nSource field should be either of these values - **domain, standalone, hosting, migrated**. It will be validated against these values when the Api call is made" }, "sourceContext": { "type": "string", "example": "website", "description": "The purchase hook from where Titan plan has been purchased by the customer \n_Purpose_ - This is used by Titan for reference and analyse the efficacy of various purchase hooks within the partner ecosystem from where customers are purchasing Titan paid plans. Some examples for sourceContext can be \"website\", \"hpanel_store\", \"cPanel_hosting_email_section\", \"cPanel_email_tab\", \"email_marketing\", etc." }, "metadata": { "type": "object", "description": "Details of associated partner order", "properties": { "partnerBrand": { "type": "string", "description": "partner brand using which order modification happened " }, "paymentMethod": { "type": "string", "description": "payment method used during purchase, i.e : credit_card, paypal, etc" }, "autoRenew": { "type": "string", "description": "true/false, auto-renew value " } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/suspendMailOrder": { "post": { "operationId": "suspendMailOrder", "summary": "Suspend Mail Order", "description": "API to suspend an existing Mail Order provisioned on Titan Mail Cloud infra on non-payment. On suspension:\n\n* Titan will suspend any orders associated with the domain name", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId", "suspensionType" ], "properties": { "titanOrderId": { "type": "number", "description": "The unique order ID against each domain provisioned with Titan", "example": 1 }, "suspensionType": { "type": "string", "description": "Reason for the suspension (e.g. abuse, expiry, or any custom value). Use expiry for non-renewal suspensions — only expiry suspensions are automatically lifted when the order renews. All other suspension types must be removed manually.", "example": "abuse" }, "note": { "type": "string", "description": "Any internal description / ticket ID, visible in the [parter-panel](https://admin.titan.email/) only to the partners support team. This is so that more info is communicated, and the next agent knows what to do with this case.", "example": "any internal description just for reference" }, "source": { "type": "string", "description": "Optional identifier for what triggered the suspension, recorded for reporting and analytics. When omitted, it defaults to partner_api_suspension_order.", "example": "partner_api_suspension_order" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/fetchOrderDetails": { "get": { "operationId": "fetchOrderDetails", "summary": "Fetch Order Details", "description": "API to fetch detailed information about a specific Mail Order on Titan Mail Cloud Infra using the titanOrderId.\n\nThis API provides comprehensive details about a mail order including account counts, domain information, and order status.", "tags": [ "Mail Order Management APIs" ], "parameters": [ { "name": "titanOrderId", "in": "query", "required": true, "schema": { "type": "number", "example": 123 }, "description": "The Titan order ID for which detailed information is required" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "titanOrderId": { "type": "number", "example": 123, "description": "The Titan order ID" }, "domainName": { "type": "string", "example": "abc.com", "description": "The mail order name associated to the Titan order ID" }, "orderId": { "type": "string", "example": "12431", "description": "The order ID stored on your end for this mail order, if any. You can use this data to correlate orders at your end and in Titan." }, "planType": { "type": "string", "example": "premium", "description": "The plan type of the mail order" }, "noOfAccounts": { "type": "number", "example": 10, "description": "Maximum number of email accounts permitted to be created within the domain. E.g. The domain might have 3 mailboxes created with a limit of 10 mailboxes. The return value will be 10 in this case" }, "noOfBillableAccounts": { "type": "number", "example": 10, "description": "Number of email accounts provisioned, which are in active/suspended state if domain is on non paid plan. Would be equal to noOfAccounts for paid domains." }, "noOfActiveAccounts": { "type": "number", "example": 6, "description": "Number of active email accounts" }, "noOfProvisionedAccounts": { "type": "number", "example": 8, "description": "Number of email accounts provisioned, which are in active/suspended state" }, "expiryDate": { "type": "string", "example": "2020-01-31", "description": "In `yyyy-MM-dd` format.\nExpiry date set against the domain" }, "status": { "type": "string", "example": "active", "description": "Current status of the order" }, "customerEmailAddress": { "type": "string", "example": "titanuser@titan.mail", "description": "Customer email address\nAll communications will be sent here\nThis will also be the primary admin for the domain" }, "serverHostName": { "type": "string", "example": "cpanel102.titan.co", "description": "hostname of the hosting-server where user's hosting order has been provisioned.\nonly available in case provisioning is via cPanel/plesk plugin" }, "source": { "type": "string", "example": "hosting", "enum": [ "domain", "standalone", "hosting", "migrated" ], "description": "The source from which the order is received - Refers to the kind of package provisioned on the partners end.\nSource field should be either of these values - **domain, standalone, hosting, migrated**. It will be validated against these values when the Api call is made" }, "titanCustomerId": { "type": "number", "example": 456, "description": "Titan's internal customer ID" }, "customerId": { "type": "string", "example": "abc123", "description": "Partner's customer ID stored on your end for this customer" }, "addonSubscriptionCounters": { "type": "object", "additionalProperties": { "x-additionalPropertiesName": "addonType", "type": "number" }, "example": { "storage_addon": 5 }, "description": "Map of addon type to the configured subscription quota for this order." } } } } } }, "400": { "description": "InvalidParameter\n- titanOrderId is not provided or is invalid" }, "403": { "description": "FORBIDDEN\n- Partner does not have access to the specified order" }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/getActiveSuspensions": { "get": { "operationId": "getActiveSuspensions", "summary": "Fetch Order Suspensions", "description": "API to fetch list of active suspensions for a Mail Order on Titan Mail Cloud Infra using the titanOrderId.", "tags": [ "Mail Order Management APIs" ], "parameters": [ { "name": "titanOrderId", "in": "query", "required": true, "schema": { "type": "number", "example": 1 }, "description": "The Titan order ID for which active suspensions are required" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suspensions": { "type": "array", "description": "", "items": { "type": "string", "description": "The suspension type.\n + `abuse`, `expiry`, `charge_back`, `etc`" } } } } } } }, "403": { "description": "FORBIDDEN\n- Partner does not own the specified order" }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/unsuspendMailOrder": { "post": { "operationId": "unsuspendMailOrder", "summary": "Unsuspend Mail Order", "description": "API to unsuspend any suspended Mail Order", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId", "suspensionType" ], "properties": { "titanOrderId": { "type": "number", "description": "The unique order ID against each domain provisioned with Titan", "example": 1 }, "suspensionType": { "type": "string", "description": "Reason for the suspension (e.g. abuse, expiry, or any custom value). Use expiry for non-renewal suspensions — only expiry suspensions are automatically lifted when the order renews. All other suspension types must be removed manually.", "example": "abuse" }, "note": { "type": "string", "description": "Any internal description / ticket ID, visible in the [parter-panel](https://admin.titan.email/) only to the partners support team. This is so that more info is communicated, and the next agent knows what to do with this case.", "example": "any internal description just for reference" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" }, "newStatus": { "type": "string", "enum": [ "active", "suspended" ], "description": "An order can have multiple suspensions added, for eg. by the partner due to a payment related issue or by titan due to abuse. After removing a suspension added by the partner, the domain may still be suspended, due to other suspensions. This newStatus reflects the status after making the unsuspend API call." }, "remainingSuspensions": { "type": "array", "description": "", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "" }, "suspenderRole": { "type": "string", "description": "" }, "suspendedOn": { "type": "string", "description": "" } } } } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/deleteMailOrder": { "post": { "operationId": "deleteMailOrder", "summary": "Delete Mail Order", "description": "API to cancel/delete existing Mail Order provisioned on Titan Cloud infra on mail order deletion or non-payment.\n* Any orders associated with the domain name will be deleted\n* All data associated with the mail order will be deleted after 30 days", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "description": "The unique order ID against each domain provisioned with Titan", "example": 1 }, "reason": { "type": "string", "description": "This is just for reference to capture reason for the deletion of the account", "example": "user terminated hosting" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/transferMailOrder": { "post": { "operationId": "transferMailOrder", "summary": "Transfer Mail Order", "description": "* Transfer Mail Order from one customer account to another\n* If a titan user profile for the new customerId does not already exist a new profile will be created using information passed or else order will be moved to the existing titan user profile.\n* Customer profile should be in the active state.\n* The order's status can be anything (active, suspended, ...)\n* `serverHostName` will be only applicable for partners using Titan's cPanel/plesk plugins.", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "description": "The unique order ID against each domain provisioned with Titan", "example": 1 }, "transferTo": { "type": "object", "required": [ "customerId", "customerEmailAddress" ], "properties": { "customerId": { "type": "string", "description": "Unique ID on your side for this customer", "example": "titanuser" }, "customerName": { "type": "string", "description": "Customer name", "example": "Titan User" }, "customerEmailAddress": { "type": "string", "description": "Customer email address\nAll communications will be sent here\nThis will also be the primary admin for the domain", "example": "titanuser@titan.mail" }, "customerCountry": { "type": "string", "description": "Customer country, 2 letter ISO Code", "example": "US" }, "serverHostName": { "type": "string", "description": "hostname of the hosting-server where user's hosting order has been provisioned\nIt's expected that only 1 server is registered with the given hostname.\nAPI fails if there are multiple" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "400": { "description": "BAD_REQUEST\n- domain customer is not in active state." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/toggleMailService": { "post": { "operationId": "toggleMailService", "summary": "Toggle Mail Service", "description": "This API is relevant if you are using Titan's cPanel plugin.
\nUsing this api, You can choose to move all domains from Titan cloud to cPanel local (or vice versa) for a particular cPanel account.\nCalling this api would result in deleting all the existing domain orders within that cPanel account and recreating them with the selected mail service.\nThe action will be applied to all existing domains and all future domains added within the cPanel account.\nAll domains in a cPanel account can either be on local or titan at a given point in time.\nThis will not result in any migration of email accounts, email data or dns; those will need to be handled by you separately.", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId", "mailService" ], "properties": { "titanOrderId": { "type": "number", "description": "The unique order ID against each domain provisioned with Titan", "example": 1 }, "mailService": { "type": "string", "enum": [ "titan", "local" ], "description": "Desired mail service to which customer wants to move", "example": "titan", "x-enum-descriptions": { "titan": "email service is hosted in the Titan cloud", "local": "email service is hosted by cPanel" } }, "mode": { "type": "string", "enum": [ "single_domain", "all_domains" ], "description": "toggling strategy, default is all_domains", "example": "all_domains", "x-enum-descriptions": { "single_domain": "only single mail order for which request is made will be toggled", "all_domains": "all mail orders under the customer are toggled" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/listMailOrders": { "get": { "operationId": "listMailOrders", "summary": "Get All Mail Orders", "description": "API to fetch list of all Mail Orders on Titan Mail Cloud Infra for a given customerId or titanCustomerId.\nRecommended to use titanCustomerId as it uniquely identifies a customer.\n\n**NOTE** for partners using Titan's cPanel/plesk plugins:\n- If Titan finds **multiple customers with same `customerId`** on different cPanel/plesk hosts:\n - The API fails with an InternalServerError as a unique customer is not found\n - If you instead want Titan to collate mail orders for given customerId across all your hosts and return in response, do let Titan know\n - the behaviour can be enabled at Titan's end via a config change\n - once the behaviour is enabled, instead of a failure you will see collated orders\n - For an order, you can differentiate customers details using `customerEmailAddress` and `serverHostName` params.\n- customerId, in case of cPanel/plesk, is the username on those servers\n- do make sure of adding any extra filtering required at your end, on host or customer email, before showing list to customers", "tags": [ "Mail Order Management APIs" ], "parameters": [ { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "example": "abc12345" }, "description": "The customer ID stored on your end for each customer\nThis is used to identify all the orders linked to a particular customer.\nEither customerId or titanCustomerId must be provided." }, { "name": "titanCustomerId", "in": "query", "required": false, "schema": { "type": "number", "example": 123 }, "description": "The customer ID stored on Titan's end.\nEither customerId or titanCustomerId must be provided." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "description": "", "type": "array", "items": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1 }, "domainName": { "type": "string", "example": "abc.com", "description": "The mail order name associated to the Titan order ID" }, "orderId": { "type": "string", "example": "12431", "description": "The order ID stored on your end for this mail order, if any. If needed, You can use this data to correlate orders at your end and in Titan.The data is returned in [listMailOrders](#operation/listMailOrders) call." }, "planType": { "type": "string", "example": "pro", "enum": [ "free", "pro", "premium", "pro_trial", "premium_trial", "ultra", "ultra_trial" ], "description": "This is the Titan mail plan. This would vary based on the plans being positioned with the partner." }, "noOfAccounts": { "type": "number", "example": 10, "description": "Maximum number of email accounts permitted to be created within the domain. E.g. The domain might have 3 mailboxes created with a limit of 10 mailboxes. The return value will be 10 in this case" }, "numberOfAccounts": { "type": "number", "example": 10, "description": "[Deprecated] Maximum number of email accounts permitted to be created within the domain. Would be discontinued going forward, please use *noOfAccounts*." }, "noOfBillableAccounts": { "type": "number", "example": 10, "description": "Number of email accounts provisioned, which are in active/suspended state if domain is on non paid plan. Would be equal to noOfAccounts for paid domains." }, "noOfActiveAccounts": { "type": "number", "example": 6, "description": "Number of active email accounts" }, "noOfProvisionedAccounts": { "type": "number", "example": 8, "description": "Number of email accounts provisioned, which are in active/suspended state" }, "expiryDate": { "type": "string", "example": "2020-01-31", "description": "In `yyyy-MM-dd` format.\nExpiry date set against the domain" }, "status": { "type": "string", "example": "active", "description": "", "enum": [ "active", "pending", "suspended", "deleted" ] }, "customerEmailAddress": { "type": "string", "example": "titanuser@titan.mail", "description": "Customer email address\nAll communications will be sent here\nThis will also be the primary admin for the domain" }, "serverHostName": { "type": "string", "example": "cpanel102.titan.co", "description": "hostname of the hosting-server where user's hosting order has been provisioned.\nonly available in case provisioning is via cPanel/plesk plugin" }, "source": { "type": "string", "example": "hosting", "enum": [ "domain", "standalone", "hosting", "migrated" ], "description": "The source from which the order is received - Refers to the kind of package provisioned on the partners end.\nSource field should be either of these values - **domain, standalone, hosting, migrated**. It will be validated against these values when the Api call is made" } } } } } } } } }, "500": { "description": "InternalServerError\n- multiple customers with **same `customerId`** on different hosts are present, and such behaviour isn't enabled.\n- can only happen in case of cPanel/plesk plugin based provisioning" }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/listAddonProducts": { "get": { "operationId": "listAddonProducts", "summary": "Fetch Addon Products and Pricing", "description": "API to fetch list of addon product details for a Mail Order on Titan Mail Cloud Infra\n\n- At least one of (titanOrderId) or (domainName, customerId) should be present in request\n- If a domain has no currency set, defaultCurrency is used for pricing of products.\n- In case Titan couldn't determine currency, req fails.", "tags": [ "Mail Order Management APIs" ], "parameters": [ { "name": "titanOrderId", "in": "query", "required": true, "schema": { "type": "number", "example": 1 }, "description": "The unique Titan order ID against which the domain is provisioned" }, { "name": "domainName", "in": "query", "required": false, "schema": { "type": "string", "example": "xyz.com" }, "description": "[Deprecated] The mail order name associated to the Titan order ID" }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "example": "abcd123" }, "description": "[Deprecated] unique id stored on your end for each customer" }, { "name": "defaultCurrency", "in": "query", "required": false, "schema": { "type": "string", "example": "USD" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" }, "domainBillingCycle": { "type": "string", "example": "monthly", "description": "billing cycle" }, "domainCurrency": { "type": "string", "example": "USD", "description": "currency" }, "addons": { "description": "", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "storage_addon, email_backup", "description": "addon type" }, "pricing": { "description": "", "type": "object", "properties": { "currency": { "type": "string", "example": "USD", "description": "" }, "billingCyclePriceMap": { "description": "", "type": "object", "properties": { "monthly": { "type": "number", "example": 2.99 }, "yearly": { "type": "number", "example": 2.49 } } } } } } } } } } } } }, "400": { "description": "BAD_REQUEST\n- server is not able to figure out currency for domain.\n- domain status is not in active or suspension state." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/checkMailOrderAvailability": { "get": { "operationId": "checkMailOrderAvailability", "summary": "Check Mail Order Availability", "description": "API to check a mail order with given domainName is available for provisioning on Titan\n\n**Availability behaviour**\n\n- **`isAvailable: true`** — the domain is available for the requesting partner to create a mail order.\n- **`isAvailable: false`** — the requesting partner already has an order for this domain; its details are returned in the response (`titanOrderId`, `customerDetails`, `orderDetails`).\n- The same domain can have a mail order under multiple partners, but only one of those orders is serviceable at a time; the others are non-serviceable. Even when the domain is already serviceable under a different partner, this API returns `true` and the partner can still create an order — it is created in a **non-serviceable** state.\n - **Serviceable** — all email services are allowed.\n - **Non-serviceable** — email services are not allowed, but the user can still log in to their account.\n- To make the order serviceable, the user must prove ownership of the domain. Once ownership is verified, an automated status-switch job makes the order serviceable and moves the previously serviceable order to non-serviceable — no manual action is required.\n- _Titan is updating its mail interfaces to guide users on how to prove domain ownership, making this state easier to understand._", "tags": [ "Mail Order Management APIs" ], "parameters": [ { "name": "domainName", "in": "query", "required": true, "schema": { "type": "string", "example": "domainname.com" }, "description": "name of domain" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "isAvailable": { "type": "boolean", "example": true, "description": "true implies domain is available and can be provisioned, false implies domain name is already-in-use and a new order with the same name cannot be provisioned." }, "titanOrderId": { "type": "number", "example": 1, "description": "In case if the order using given domain name is provisioned by you, this will contain its titanOrderId.\nIf not provisioned by you then this field will not be present." }, "customerDetails": { "type": "object", "description": "Details of associated customer", "properties": { "titanCustomerId": { "type": "number", "example": 123, "description": "unique customer id at Titan's end" }, "customerId": { "type": "string", "example": "customer", "description": "customer id at your end" }, "customerEmail": { "type": "string", "example": "customer@domain.com", "description": "customer email" } } }, "orderDetails": { "type": "object", "description": "Details of associated order", "properties": { "noOfAccounts": { "type": "number", "example": 1000, "description": "max account limit for the domain" }, "createdAt": { "type": "number", "example": 1645315200000, "description": "Creation timestamp in epoch milliseconds." }, "expiryDate": { "type": "string", "example": "2022-02-20", "description": "In `yyyy-MM-dd` format." }, "planType": { "type": "string", "example": "pro", "enum": [ "free", "pro", "premium", "pro_trial", "premium_trial", "ultra", "ultra_trial" ], "description": "This is the Titan mail plan. This would vary based on the plans being positioned with the partner." }, "status": { "type": "string", "example": "active", "enum": [ "active", "pending", "suspended", "deleted" ], "description": "" }, "source": { "type": "string", "example": "source", "description": "source provided while provisioning the domain" } } } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/checkMailOrderReactivationEligibility": { "get": { "operationId": "checkMailOrderReactivationEligibility", "summary": "Check Mail Order Reactivation Eligibility", "description": "API to check if deleted Mail Order can be reactivated.", "tags": [ "Mail Order Management APIs" ], "parameters": [ { "name": "titanOrderId", "in": "query", "required": true, "schema": { "type": "number", "example": 1 }, "description": "The unique Titan order ID against which the domain is provisioned" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reactivationAllowed": { "type": "boolean", "example": true, "description": "" }, "reason": { "type": "string", "example": "DOMAIN_NOT_IN_DELETED_STATE", "enum": [ "DOMAIN_NOT_IN_DELETED_STATE", "NON_TITAN_CLOUD_DOMAIN", "USER_NOT_ACTIVE_IN_SYSTEM", "DOMAIN_PURGED", "ACTIVE_DOMAIN_EXISTS" ], "description": "This is an enum with values. This field will be present if reactivationAllowed is false\n\n- `DOMAIN_NOT_IN_DELETED_STATE`: The domain is not in a deleted state\n- `NON_TITAN_CLOUD_DOMAIN`: The domain is not on a Titan-managed plan, so reactivation through this API is not supported\n- `USER_NOT_ACTIVE_IN_SYSTEM`: The user associated with this domain is not active in the system\n- `DOMAIN_PURGED`: The domain's purge date has passed and it can no longer be recovered\n- `ACTIVE_DOMAIN_EXISTS`: Another active domain already exists with the same name" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/reactivateMailOrder": { "post": { "operationId": "reactivateMailOrder", "summary": "Reactivate Mail Order", "description": "API to reactivate deleted mail order. This API must be called after [Check Mail Order Reactivation Eligibility API](#operation/checkMailOrderReactivationEligibility)", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "400": { "description": "BAD_REQUEST\n- Domain not in valid state\n- Non deleted domain with same name exists in system\n- Domain purge limit reached" }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/completePurchase": { "post": { "operationId": "completePurchase", "summary": "Complete Purchase", "description": "API to confirm payment for complete purchase of a Mail Order on the Titan Mail Cloud infra\n\nAPI consumers can use [Create Mail Order](#operation/createMailOrder)/[Modify Mail Order](#operation/modifyMailOrder) APIs for order provisioning and upgrades/renewals.\n\nThis API serves a different (and more deeply integrated) case where partner is handling payments for some purchases user initiated in Titan's [Domain Control Panel](https://manage.titan.email).\n\nFlow:\n1. User initiates a payment action (adds some addon to cart, increases mailboxes, upgrades plan) on Control Panel.\n2. For payment Titan redirects user to a [payment url](#operation/upgrade) partners provide, passing on a trackingId as part of jwt\n3. Partner takes payment from user and triggers this API (Complete Purchase) with the same trackingId\n4. Titan records the payment and makes the purchases associated with that trackingId.", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId", "trackingId", "chargedAmount" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" }, "domainName": { "type": "string", "example": "xyz.com", "description": "[Deprecated] The mail order name associated to the Titan order ID" }, "customerId": { "type": "string", "example": "abcd123", "description": "[Deprecated] unique id stored on your end for each customer" }, "trackingId": { "type": "string", "example": "qwe-123-asd-321", "description": "Payment tracking token fetched from Titan's control panel" }, "currency": { "type": "string", "example": "USD", "description": "This is the currency in which the customer is being charged for Titan mail. also updates domain to this currency" }, "chargedAmount": { "type": "number", "example": 12.2, "description": "Total amount charged by the partner to the end customer in the customer's currency for this purchase including taxAmount.\nPrecision upto 2 decimal places." }, "chargedUSDAmount": { "type": "number", "example": 12.2, "description": "The value of chargedAmount in USD. If this field is null then open-exchange rates are used to calculate this field" }, "discountAmount": { "type": "number", "example": 1.5, "description": "Any ad hoc discount given to the customer for this purchase.\nThis should be passed in the original currency in which amount was charged to the customers." }, "taxAmount": { "type": "number", "example": 0.2, "description": "Amount collected from the user as TAX amount in the customer's currency for this purchase.\nPrecision upto 2 decimal places." }, "paymentTxnId": { "type": "string", "example": "txnId", "description": "Payment Transaction ID in your system." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "409": { "description": "ConflictRequest\n- domain not in same state as during initiating purchase or no change applied on the domain.\n\nPAYMENT_EXPIRED\n- if trackingId has already been used to complete purchase." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/dnsLookup": { "post": { "operationId": "dnsLookup", "summary": "DNS Verification", "description": "API used to check whether a mail order has been verified with the correct MX/SPF records. Titan checks for MX/SPF verification in following cases:\n* Once order is created, records are checked automatically once on the same day(after few hours) and once on the next day.\n* On accessing Titan Control panel, records are checked automatically to show missing records info to the user. Records are rechecked in case user clicks on 'Check again' option in Titan Control panel.", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" }, "domainExists": { "type": "boolean", "example": true, "description": "Returns true if the domain is registered and false if the domain does not exist" }, "nsRecords": { "type": "array", "items": { "type": "string" }, "description": "Returns the Nameservers currently setup against the domain" }, "spfRecords": { "type": "array", "items": { "type": "string" }, "description": "" }, "mxRecords": { "type": "array", "items": { "type": "string" }, "description": "" }, "mxVerified": { "type": "boolean", "example": true, "description": "Provides a True or False value on whether the MX records are correctly setup" }, "spfVerified": { "type": "boolean", "example": true, "description": "Provides a True or False value on whether the SPF records are correctly setup" }, "lenientSPF": { "type": "boolean", "example": true, "description": "Provides a True or False value on whether the domain is permitted to send/receive email with the incorrect SPF records" } } } } } }, "400": { "description": "BAD_REQUEST\n- Domain exists in deleted or pending state in titan infra. \"desc\" will include information for failure." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/generateDKIMKeys": { "post": { "operationId": "generateDKIMKeys", "summary": "Generate DKIM Keys", "description": "API to generate DKIM keys for a mail order on Titan Mail Cloud infra. If keys already exist return existing Keys.", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" }, "txtRecord": { "type": "string", "example": "v=DKIM1; k=rsa; p=qwe123", "description": "E.g : v=DKIM1; k=rsa; p=" }, "selector": { "type": "string", "example": "titan", "description": "Selector value for DKIM public key record in your DNS." } } } } } }, "403": { "description": "FORBIDDEN\n- Operation not allowed if the domain's mail service is not hosted on the Titan Cloud infra (e.g. domains moved to local/cPanel hosting via [Toggle Mail Service](#operation/toggleMailService))." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/modifyMailCustomer": { "post": { "operationId": "modifyMailCustomer", "summary": "Modify Mail Customer", "description": "- API to modify mail customer `emailAddress`, `name` and `country`.\n- API will change these properties for all mail orders associated with the titanOrderId mail customer.\n- Partner will receive [MAIL_CUSTOMER_UPDATED](#mailCustomerUpdatedNotification) notification whenever any of above 3 properties change\n\n**Note**:\n- To change mail customer customerId call [transferMailOrder API](#operation/transferMailOrder) for every mail order associated with this mail customer.", "tags": [ "Mail Order Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1 }, "customerName": { "type": "string", "example": "Adam", "description": "The new customer name" }, "customerEmailAddress": { "type": "string", "example": "adma1231@gmail.com", "description": "The new customer email" }, "customerCountry": { "type": "string", "example": "US", "description": "Should be the 2 letter ISO Code, country from which the customer is accessing partner website/making the purchase.\nTitan will use this to identify the localized pricing based on the location of the customer in cases where Titan mail is managing the billing." }, "newCustomerId": { "type": "string", "example": "toBeUpdatedCustomerId", "description": "The new customer Id." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/syncMailCustomer": { "post": { "operationId": "syncMailCustomer", "summary": "Sync Mail Customer API", "description": "API to sync domains associated with mail customer on cpanel/plesk server.", "tags": [ "Mail Customer APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "serverHostname" ], "properties": { "username": { "type": "string", "example": "abcd123", "description": "customer cpanel/plesk username" }, "serverHostname": { "type": "string", "example": "server101.com", "description": "server hostname" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "400": { "description": "BAD_REQUEST\n- server hostname is not found." }, "404": { "description": "UserNotFound\n- when the customer is not active on cpanel/plesk server." }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/setCatchallConfig": { "post": { "operationId": "setCatchallConfig", "summary": "Set Catch-all Configuration", "description": "API to activate catch all account for a Mail Order on Titan Mail Cloud infra", "tags": [ "Catch-all Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId", "email" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" }, "email": { "type": "string", "example": "info@xyz.com", "description": "Specify the email account associated with the mail order that needs to be set to the catch all emails." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/removeCatchallConfig": { "post": { "operationId": "removeCatchallConfig", "summary": "Remove Catch-all Configuration", "description": "API to remove catch all email account for a Mail Order on Titan Mail Cloud infra", "tags": [ "Catch-all Management APIs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "titanOrderId" ], "properties": { "titanOrderId": { "type": "number", "example": 1, "description": "The unique order ID against each domain provisioned with Titan" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/getCatchallConfig": { "get": { "operationId": "getCatchallConfig", "summary": "Get Catch-all Configuration", "description": "API to fetch catch all config for a Mail Order on Titan Mail Cloud infra\n\n**Note**: In case catchall is not activated, the default behaviour is to reject all emails for unknown email addresses", "tags": [ "Catch-all Management APIs" ], "parameters": [ { "name": "titanOrderId", "in": "query", "required": true, "schema": { "type": "number", "example": 1 }, "description": "The unique Titan order ID" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reqID" ], "properties": { "reqID": { "type": "string", "example": "server.req.id" }, "email": { "type": "string", "example": "abc@xyz.com", "description": "The catch-all email account setup against the domain" } } } } } }, "default": { "$ref": "#/components/responses/commonErrorCodes" } } } }, "/partner/autoLogin": { "get": { "operationId": "autoLogin", "summary": "Autologin Titan admin into Titan control panel", "description": "When your user wants to login to the control panel redirect him/her to Titan Mail control panel URL with short term validity AuthToken.\n\n`https://manage.titan.email/partner/autoLogin?partnerId=&jwt=§ion=
&action=&email=&locale=`\n\n#### Parameters\n+ partnerId (string, required)\n+ jwt (string, required)\n + Jwt Request Body\n ``` json\n {\n \"titanOrderId\": 123,\n \"exp\": 345678974327\n }\n ```\n + titanOrderId (number, required)\n + The unique Titan order ID against which the domain is provisioned\n + exp (number, required)\n + The \"exp\" ([expiration time in epoch seconds](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing\n+ section (string, optional)\n + Control panel Section to open, Specify the section within the control panel to be loaded\n + home (default)\n + email-accounts\n + internal-forward\n + catch-all-email\n + device-download\n + configure-desktop\n + domain-verification\n + import-email\n + billing-and-upgrade\n + buy-email-account\n+ action (string, optional)\n + `launch-email-creation` used with `email-accounts` section\n + `paymentSuccess` used with `billing-and-upgrade` section\n+ email (string, optional)\n + required with `launch-email-creation` action\n+ locale (string, optional)\n + Specifies the language to be set within the Email Control Panel.\n List of support Titan languages - [link](https://docs.google.com/document/d/16ZHxYOmp1GpWm_oEWMMvSXEX-BcCj0B06vR1qrL-_yM/edit)\n Default is `en-us`", "tags": [ "Redirection between Partner and Titan" ], "parameters": [ { "name": "partnerId", "in": "query", "required": true, "schema": { "type": "string", "example": "PARTNER_ID" } }, { "name": "jwt", "in": "query", "required": true, "schema": { "type": "string", "example": "JWT_TOKEN" } }, { "name": "section", "in": "query", "required": false, "schema": { "type": "string", "example": "home", "enum": [ "home", "email-accounts", "internal-forward", "catch-all-email", "device-download", "configure-desktop", "domain-verification", "import-email", "billing-and-upgrade", "buy-email-account" ] }, "description": "Control panel Section to open, Specify the section within the control panel to be loaded" }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "example": "launch-email-creation" } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "example": "james@xyz.com" } }, { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "example": "en-us" }, "description": "Specifies the language to be set within the Email Control Panel.\nList of support Titan languages - [link](https://docs.google.com/document/d/16ZHxYOmp1GpWm_oEWMMvSXEX-BcCj0B06vR1qrL-_yM/edit)\nDefault is `en-us`" } ], "responses": { "302": { "description": "Redirect to Titan Control Panel" } } } }, "/partner/cpWidget": { "get": { "operationId": "cpWidget", "summary": "Embedding Titan iframe control panel within Partner environment", "description": "iFrame Source URL :\n`https://manage.titan.email/partner/cpWidget?partnerId=&jwt=§ion=
&action=&email=&locale=&theme=`\n\n- Pass attribute allow=\"clipboard-write\" in iframe tag to allow copy functionality in embedded control panel e.g `