API Documentation Download OpenAPI specification
API reference›Mail Order Management APIs

Create Mail Order

POSThttps://bll.titan.email/partner/createMailOrder

API to provision a Mail Order on Titan.

Notes :

  • 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.

Body

application/json
domainNamestringrequired

Customer mail order being provisioned The order provisioned in Titanmail is against the domainName provided by the partner within the API

Example: xyz.com
orderIdstring

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 call.

Example: 12431
customerIdstringrequired

The customer ID stored on your end for each customer This is used to identify all the orders linked to a particular customer

Example: abcd123
customerNamestringoptional

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.

Example: Adam Smith
customerEmailAddressstringoptional

The email address with which the customer registers on the partner website This 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 This email will be used by the customer to login into Control Panel. This user will also be the primary admin for the domain

Example: adam@gmail.com
alternateEmailAddressstringoptional

This email will be used to send emails, in case email delivery fails for customerEmailAddress

Example: abc@xyz.com
passwordstringoptional

Password for signing into Domain Control Panel

Example: asdfqwe
customerCountrystringoptional

Should be the 2 letter ISO Code, country from which the customer is accessing partner website/making the purchase. Titan will use this to identify the localized pricing based on the location of the customer in cases where Titan mail is managing the billing.

Example: US
planTypestring · enumrequired

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

Example: pro
Possible values: free pro premium pro_trial premium_trial ultra ultra_trial
noOfAccountsnumberoptional

Required for Paid Plans The number of accounts or mailboxes to be provisioned against the domain. This is used as a limiting parameter for the user to create accounts within the Control Panel. E.g. if this is set to 2, the user will not be allowed to create more than 2 mailboxes

Example: 10
titanResellerIdnumberoptional

Titan Reseller ID for reseller-level branding. If provided, the order will use the branding associated with this reseller. If null, falls back to partner's default branding.

Example: 456
expiryDatestringoptional

In yyyy-MM-dd format.
Required for Paid and Trial Plans.
If 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.
If 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.

Example: 2020-02-20
paymentTxnIdstringoptional

Partner should provide transactionId when the order is provisioned on paid plan or associated order is paid

Example: qweradsf
chargedAmountnumberoptional

Required for Paid Plans Total 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. Used primarily for reference and reporting on Titan's end. This is applicable only in the case of a paid plan. For free/trial plans, this should be passed as "0"

Example: 1.1
currencystringoptional

Should be 3 letter ISO code This 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.

Example: USD
chargedUSDAmountnumberoptional

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.

Example: 1.1
discountAmountnumberoptional

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.

Example: 0.1
taxAmountnumberoptional

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.

Example: 0.1
billingCyclestring · enumoptional

This defines the period for which the customer has been billed for Titan mail by the partner. This is for Titan to track the billing cycle/details for that customer. Existing options are

Example: monthly
Possible values: monthly quarterly semesterly yearly two_yearly three_yearly four_yearly five_yearly
localestringoptional

Specifies the language to be set within the Email Control Panel. List of support Titan languages - link Default is set to en-us

Example: en-gb
sourcestring · enumoptional

The source from which the order is received - Refers to the kind of package provisioned on the partners end. Source field should be either of these values - domain, standalone, hosting, migrated. It will be validated against these values when the Api call is made

Example: hosting
Possible values: domain standalone hosting migrated
sourceContextstringoptional

The purchase hook from where Titan plan has been purchased by the customer
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.

Example: website
metadataobjectoptional

Details of associated partner order

Show propertiesHide properties
associatedOrderExpiryDatestringoptional

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

associatedOrderPlanTypestringoptional

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

cpanelHostNamestringoptional

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

cpanelUserNamestringoptional

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

partnerBrandstringoptional

partner brand using which order creation happened

paymentMethodstringoptional

payment method used during purchase, i.e : credit_card, paypal, etc

autoRenewstringoptional

true/false, auto-renew value

firstEmailAccountobjectoptional

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. Purpose - To allow partners provision first emailAccount along with order in 1 API call

Show propertiesHide properties
emailstringrequired

emailAddress of the email account to be created

Example: james@xyz.com
passwordstringrequired

password of the email account to be created, password should be at least 6 characters long

Example: password
isAdminbooleanoptional

Set true if emailAccount holder is admin. Default value of this field is true.

Example: true
namestringoptional

Name of the email account holder

Example: James
firstNamestringoptional

The first name of the customer for whom the email address is being created.

Example: James
lastNamestringoptional

The last name of the customer for whom the email address is being created.

Example: Bond
alternateEmailstringoptional

alternate email for this mail account, reset password tokens are sent to alternate email

Example: james@gmail.com
metadataobjectoptional

Additional metadata for capturing information of account

Show propertiesHide properties
isFreebooleanoptional

Specifies whether the account is free or not

Example: true
sendWelcomeEmailbooleanoptional

Specifies whether or not to send email to customer for this newly created order. Default value of this flag is true

Example: true

Responses

200OKapplication/json
reqIDstringrequired
Example: server.req.id
titanOrderIdnumberrequired
Example: 1
statusstring · enum
  • 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.
Example: active
Possible values: active pending suspended deleted
firstEmailAccountDetailsobject
Show propertiesHide properties
webmailAutoLoginTokenstring

This token can be used to auto login into titan webmail , token validity is 1 hour. Check here to see How to use this token

titanAccountIdnumber

unique account id at Titan's end.

Example: 1
400BAD_REQUEST
  • domain for email of firstEmailAccount does not match.
  • Domain already exists with different details. happens multiple api calls, but with different data values.
  • On multiple requests, if the data is same then, Titan returns success response with domain status and firstAccount details.
  • 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.
See General Errors for other errors that this API can return.
POST/partner/createMailOrder
curl https://bll.titan.email/partner/createMailOrder \
  --request POST \
  --header 'Authorization: API.Key' \
  --header 'Content-Type: application/json' \
  --data '{
  "domainName": "xyz.com",
  "orderId": "12431",
  "customerId": "abcd123",
  "customerName": "Adam Smith",
  "customerEmailAddress": "adam@gmail.com",
  "alternateEmailAddress": "abc@xyz.com",
  "password": "asdfqwe",
  "customerCountry": "US",
  "planType": "pro",
  "noOfAccounts": 10,
  "titanResellerId": 456,
  "expiryDate": "2020-02-20",
  "paymentTxnId": "qweradsf",
  "chargedAmount": 1.1,
  "currency": "USD",
  "chargedUSDAmount": 1.1,
  "discountAmount": 0.1,
  "taxAmount": 0.1,
  "billingCycle": "monthly",
  "locale": "en-gb",
  "source": "hosting",
  "sourceContext": "website",
  "metadata": {
    "associatedOrderExpiryDate": "string",
    "associatedOrderPlanType": "string",
    "cpanelHostName": "string",
    "cpanelUserName": "string",
    "partnerBrand": "string",
    "paymentMethod": "string",
    "autoRenew": "string"
  },
  "firstEmailAccount": {
    "email": "james@xyz.com",
    "password": "password",
    "isAdmin": true,
    "name": "James",
    "firstName": "James",
    "lastName": "Bond",
    "alternateEmail": "james@gmail.com",
    "metadata": {
      "isFree": true
    }
  },
  "sendWelcomeEmail": true
}'
Response
{
  "reqID": "server.req.id",
  "titanOrderId": 1,
  "status": "active",
  "firstEmailAccountDetails": {
    "webmailAutoLoginToken": "string",
    "titanAccountId": 1
  }
}