Info |
---|
This page is a reference manual for API to be used for developing a custom solution of automatic account provisioning. MailUp APS for Plesk is built on top of this API and it should be your first option for account provisioning. As for the MailUp APS, the access to this API is not "self service", you should first contact us in order to ask for enabling your application for account provisioning and to agree on setup details. |
...
On this page:
Table of Contents |
---|
Management
Use these methods to retrieve informations about your environment (profiles, packages and languages) and configure your environment.
Note that all management resource requests ignore ExternalUserId value, so your client can perform these requests having or not this value.
Anchor | ||||
---|---|---|---|---|
|
Description | Get retailer-defined profiles | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) |
|
Anchor | ||||
---|---|---|---|---|
|
To retrieve available languages you need to provide this parameter:
...
Description | Get retailer-defined profile-packages relationship | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) |
|
Errors
HTTP Status Code | When | Message |
---|---|---|
403 Forbidden | Unexisting id_profile | You cannot access to provided profile. |
id_profile not assigned to specified Retailer account |
Note
- Min e Max equals to the minimum and maximum number of packages manageable by selected profile.
Anchor GetLanguages GetLanguages
Get the available languages by profile
GetLanguages | |
GetLanguages |
To retrieve available packages you need to provide this parameter:
...
Description | Get the available languages by profile | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
403 Forbidden | Unexisting id_profile | You cannot access to provided profile. |
id_profile not assigned to specified IdConsoleRetailer |
Account
Use these methods to manage retailer's customers accounts. With these methods you can create new accounts, add or remove packages and get what you need to login to accounts.
...
- AccessToken contains an empty ExternalUserId
- AccessToken contains an ExternalUserId that hasn't got the the right scope to perform required operation.
Anchor CreateAccount CreateAccount
Create a retailer's customer account
CreateAccount | |
CreateAccount |
The process to create an account could take some time. To create a new account you have to provide this information:
...
Description | Create a retailer's customer account | ||||
---|---|---|---|---|---|
HTTP Method | POST | ||||
URL |
| ||||
JSON request (example) |
| ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | Unexisting lang value into the TwoLetterISOLanguageName list. | Invalid language. |
ExternalUserId empty. | Invalid ExternalUserId. | |
403 Forbidden | No profiles for the ResellerId authentication code value. | You cannot access to provided profile. |
Internal error occurred | Code: -1 Description: Unknown account activation status. | |
You are not able to create this account | Code: 2 Description: Error | |
Language provided is not allowed for this retailer's edition | Code: 3 Description: Language '{lang}' is not available for profile {id_Profile}. | |
IpAddress is null, empty or IPAddress.TryParse fails | Code: 4 Description: IpAddress cannot be null, empty or invalid. | |
IpAddress is null, empty or EmailHelper.ValidateAddress fails | Code: 5 Description: Email cannot be null, empty or invalid. | |
Request contains some null, empty or invalid domain fields | Code: 6 Description: Domains cannot be null, empty or invalid. | |
One or more domains not available | Code = 7; Description: Custom domain not available. | |
Code: 8; Description: Link tracking domain not available | ||
Code: 9; Description: Image tracking domain not available | ||
Invalid retailer's service information | Code: 10; Description: Service name cannot be null, empty or invalid. | |
Code: 11; Description: Service url cannot be null, empty or invalid. | ||
Code: 12; Description: Service logout url cannot be null, empty or invalid. |
Note
- It is possile to create ONLY ONE Trial Control Panels per ExternalUserId. If you try to create more Trial using the same ExternalUserId the response contains Code: 1, Description: Processing until the process ends and then it contains Code: 2, Description: Error.
- It is possile to create MORE non Trial Control Panels per ExternalUserId. If you try to create more non Trial using the same or another ExternalUserId the response contains Code: 1, Description: Processing until the process ends and then it contains Code: 0, Description: Ok.
Anchor | ||||
---|---|---|---|---|
|
Finalize your account creation process checking its status. To finalize a new account creation process you have to provide this information:
...
Description | Get retailer's customer account profile activation status | ||||||
---|---|---|---|---|---|---|---|
HTTP Method | GET | ||||||
URL |
| ||||||
JSON request (example) | none | ||||||
JSON response (example) |
| ||||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails | ||
id_Activation is not a number | Invalid activation. | |
403 Forbidden | Unknown account activation status phase
| Code = -1 Description = Unknown account activation status |
Account activation failed | Code = 2 Description = Error | |
Link or image tracking domains, service name, url or logout url cannot be set | Code = 3 Description = An error occurred finalizing account creation |
Note
- the IdAccount field contains a value ONLY when the new account is propertly created, so Code field contains the 0 - OK code value.
Change retailer’s customer account profile
Method to change the profile. To change account account profile you have to provide this information:
...
Description | Change retailer’s customer account profile | ||
---|---|---|---|
HTTP Method | PUT | ||
URL |
| ||
JSON request (example) | none | ||
JSON response (example) | none | ||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails | ||
403 Forbidden | Invalid id_profile
| You cannot access to provided profile. |
Invalid id_account | You cannot access to provided account. |
Note
the return value is the HTTP Status code of the response. API executes this operation asynchronously. Every time the client invokes the method, it returns a code. If this code tells that the operations are still in progress the resource returns an 202 Accepted status code; otherwise returns a 200 OK status code. If an error occurred it returns 500 Internal Server Error.
the client can invoke the resource as many times as it wants.
Get retailer's customer account status
Method to verify the account status. To retrieve the account status you have to provide this information:
...
Description | Get retailer’s customer account status | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails | ||
403 Forbidden | Invalid Id_Account | You cannot access to provided account. |
Note
- La chiamata ritorna -1 se il metodo GetAccountStatus dei servizi ADM ritorna come ReturnCode 1 (Processing) o 2 (Error). Tale descrizione del ReturnCode viene settata come description in modo che si possa capire il motivo del fallimento. In realtà ReturnCode, in questo caso, varrà 0 (Ok) oppure 2 (Error) e MAI 1 (Processing).
- La proprietà ActivePacks restituisce informazioni relative allo stato attuale dei pacchetti. Il campo Quantity restituisce la somma algebrica dei pacchetti aggiunti/rimossi, mentre CurrentQuantity fornisce informazioni relative a quanti pacchetti sono attualmente in uso (un pacchetto potrebbe essere stato rimosso, ma l'effettiva rimozione avverrà a fine mese)
Disable retailer's customer account
Method to disable an account.
...
Description | Disable retailer's customer account | ||||
---|---|---|---|---|---|
HTTP Method | PUT | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Enable reseller's customer account info
Method to enable a disabled account. A disabled account cannot be enabled in the future.
...
Description | Enable a disabled retailer's customer account | ||||
---|---|---|---|---|---|
HTTP Method | PUT | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Unprovide reseller's customer account
Method to unprovide an account. An unprovided account cannot be enabled in the future.
...
Description | Unprovide a retailer's customer account | ||||
---|---|---|---|---|---|
HTTP Method | DELETE | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Add package to retailer's customer account
Method to add packages to selected account.
...
Description | Add package to retailer's customer account | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | |||||||||||||||||||
URL |
| |||||||||||||||||||
JSON request (example) |
| |||||||||||||||||||
JSON response (example) |
| |||||||||||||||||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | IdPack is not numeric | Invalid pack. |
ExternalUserId empty. | Invalid ExternalUserId. | |
ExternalUserId validation fails |
Note
- It is impossible to remove packages from TRIAL profile
- It is impossible to remove credits-related packages
Anchor | ||||
---|---|---|---|---|
|
The resource allows to retrieve the logins available for this account/console. It is necessary if the retailer allows his customers to add more administrators to an account.
...
Description | Unprovide a retailer's customer account | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Login?PageSize=2&PageNumber=1 |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Get retailer's customer account login url
Method provides the URL to login to account.
...
Description | Get retailer's customer account login url | ||||
---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Errors
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |