This page is a reference manual for the API to be used for developing a custom solution of automatic account provisioning. MailUp APS 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 to ask for enabling your application for account provisioning and to agree on setup details.

On this page:

Management

Use these methods to retrieve pieces of information 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.

Get retailer-defined profiles

Description	Get retailer-defined profiles
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile
JSON request (example)	none
JSON response (example)	Click here to expand... HTTP/1.1 200 OK { "IsPaginated":false, "Items":[ { "ClientCode":1, "Description":"Trial", "Id":1046, "Name":"Trial" }, { "ClientCode":2, "Description":"Economy", "Id":1047, "Name":"Economy" }, { "ClientCode":3, "Description":"Premium", "Id":1048, "Name":"Premium" }], "PageNumber":0, "PageSize":20, "Skipped":0, "TotalElementsCount":3 }
Paging and filtering (example)	Retrieving the first page with two items: https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile?PageSize=2 Retrieving the second page with two items: https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile?PageSize=2&PageNumber=1

Get retailer-defined packages by profile

To retrieve available languages you need to provide this parameter:

	Required	Where	Description
id_Profile	X	URL	See get profile

Description	Get retailer-defined profile-packages relationship
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Pack
JSON request (example)	none
JSON response (example)	Click here to expand... HTTP/1.1 200 OK { "IsPaginated":false, "Items":[ { "ClientCode":1, "Description":"Pacchetto che consente di aumentare la velocità di invio di 300 mail\/ora", "Id":534, "Max":5, "Min":1, "Name":"VelocitaAggiuntiva300" }, { "ClientCode":2, "Description":"Pacchetto che consente di aggiungere 300 crediti alla console", "Id":535, "Max":65535, "Min":1, "Name":"Crediti300" }], "PageNumber":0, "PageSize":20, "Skipped":0, "TotalElementsCount":2 }
Paging and filtering (example)	Retrieving the first page with two items: https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Pack?PageSize=2 Retrieving the second page with two items: https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Pack?PageSize=2&PageNumber=1

Errors

HTTP Status Code	When	Message
403 Forbidden	Unexisting id_profile	You cannot access the provided profile.
403 Forbidden	id_profile not assigned to a specified Retailer account	You cannot access the provided profile.

Note

Min e Max equals the minimum and a maximum number of packages manageable by selected profile.

Get the available languages by profile

To retrieve available packages you need to provide this parameter:

	Required	Where	Description
id_Profile	X	URL	See get profile

Description	Get the available languages by profile
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Lang
JSON request (example)	none
JSON response (example)	Click here to expand... HTTP/1.1 200 OK [ "JA", "ID", "IT", "ES", "FR", "PT", "ZH", "EN" ]
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
403 Forbidden	Unexisting id_profile	You cannot access the provided profile.
403 Forbidden	id_profile not assigned to specified IdConsoleRetailer	You cannot access the provided profile.

Account

Use these methods to manage retailers' customer's accounts. With these methods, you can create new accounts, add or remove packages and get what you need to log in to accounts.

Note that all account resource requests need an ExternalUserId value, so you have to authenticate specifying the retailer's customer unique identifier. APIs validates client requests forbidden the access if:

AccessToken contains an empty ExternalUserId
AccessToken contains an ExternalUserId that hasn't got the right scope to perform the required operation.

Create a retailer's customer account

The process to create an account could take some time. To create a new account you have to provide this information:

	Required	Where	Description
id_Profile	X	URL	See get profile
lang	X	URL	See get languages
IpAddress	X	Body	Your client IP address
Email	X	Body	Your customer's email address
CustomDomain	X	Body	Your product or your customer domain
CustomSubdomain	X	Body	Your product or your customer subdomain to address this service
ServiceName	X	Body	Your product name
ServiceUrl	X	Body	Your product web site
ServiceLogoutUrl	X	Body	Address to redirect the customer when logouts
UserAgent		Body	Your client user agent
Referer		Body	Your client referer

This method returns an activation identifier to prevent client hanging. When the method responds, your clients have to poll the activation status method to understand when the creation process ends. The response could contain domains that should be redirected to MailUp CNAMEs adding DNS records.

Description	Create a retailer's customer account
HTTP Method	POST
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/Activation/Profile/{id_Profile}/Language/{lang}
JSON request (example)	Click here to expand... { "IpAddress":"192.168.0.1", "Email":"service@retailer.it", "CustomDomain":"power-email-marketing.it", "CustomSubdomain":"customer123", "ServiceName":"Power email marketing", "ServiceUrl":"www.power-email-marketing.it/info", "ServiceLogoutUrl":"www.power-email-marketing.it", "Referer":"", "UserAgent: "" }
JSON response (example)	Click here to expand... HTTP/1.1 200 OK { "Code":0, "Description":"Ok", "IdActivation":9054, "Hash":"767eed52-be08-4eb4-8658-5db4eaa215e1", "ControlPanelDomain":"customer123.mailadmin.io", "ImageTrackingDomain":"img.customer123.t.power-email-marketing.it", "LinkTrackingDomain":"customer123.t.power-email-marketing.it" }
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	Unexisting lang value into the TwoLetterISOLanguageName list.	Invalid language.
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
403 Forbidden	No profiles for the ResellerId authentication code value.	You cannot access the 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.
	The 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 possible to create ONLY ONE Trial Control Panels per ExternalUserId. If you try to create more Trials 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 possible to create MORE non Trial Control Panels per ExternalUserId. If you try to create more non Trials 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.

Get retailer's customer account profile activation status

Finalize your account creation process checking its status. To finalize a new account creation process you have to provide this information:

	Required	Where	Description
id_Activation	X	URL	See create account

Description	Get retailer's customer account profile activation status
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/Activation/{id_Activation}/Status
JSON request (example)	none
JSON response (example)	Click here to expand... The system is creating your new account: HTTP/1.1 201 Accepted { "Code":1, "Description":"Processing", "IdAccount":0 } New account created successfully: HTTP/1.1 200 OK { "Code":0, "Description":"Ok", "IdAccount":23052 }
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
	ExternalUserId validation fails	Invalid ExternalUserId.
	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 properly created, so the Code field contains the 0 - OK code value.

Change retailer’s customer account profile

Method to change the profile. To change your account profile you have to provide this information:

	Required	Where	Description
id_Account	X	URL	See activation status response
id_Profile	X	URL	See get profiles

Description	Change retailer’s customer account profile
HTTP Method	PUT
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Profile/{id_Profile}
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.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.
403 Forbidden	Invalid id_profile	You cannot access the provided profile.
403 Forbidden	Invalid id_account	You cannot access the 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 a 202 Accepted status code; otherwise returns a 200 OK status code. If an error occurred it returns a 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:

	Required	Where	Description
id_Account	X	URL	See activation status response

The table below shows the possible status, specifying related response fields meaning:

Status	Response Code field value	Response Description field value
Error / Processing	-1	Error or Processing
Enabled	0	Enabled
Disabled	1	Disabled
Unprovided	2	Unprovided

Description	Get retailer’s customer account status
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}
JSON request (example)	none
JSON response (example)	Click here to expand... { "Code":0, "Description":"Enabled", "ActivePacks":[ {"CurrentQuantity":0,"Id":534,"Quantity":0}, {"CurrentQuantity":0,"Id":535,"Quantity":0}, {"CurrentQuantity":0,"Id":536,"Quantity":0}, {"CurrentQuantity":0,"Id":537,"Quantity":0}, {"CurrentQuantity":0,"Id":538,"Quantity":0} ], "Credits":300, "IdAccount":23053, "IdProfile":1401, "ValidFrom":"2015-10-14 22:00:00Z", "ValidTo":"2016-10-14 22:00:00Z" }
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.
403 Forbidden	Invalid Id_Account	You cannot access the 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.

	Required	Where	Description
id_Account	X	URL	See activation status response
Enable		Querystring	Could be FALSE

Description	Disable retailer's customer account
HTTP Method	PUT
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account} or https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}?Enable=false
JSON request (example)	none
JSON response (example)	Click here to expand... { "Code":0, "Description":"Ok" }
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.

Enable reseller's customer account info

Method to enable a disabled account. A disabled account cannot be enabled in the future.

	Required	Where	Description
id_Account	X	URL	See activation status response
Enable	X	Querystring	Must be TRUE

Description	Enable a disabled retailer's customer account
HTTP Method	PUT
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_account}?Enable=true
JSON request (example)	none
JSON response (example)	Click here to expand... { "Code":0, "Description":"Ok" }
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.

Unprovide reseller's customer account

Method to unprovide an account. An unprovided account cannot be enabled in the future.

	Required	Where	Description
id_Account	X	URL	See activation status response

Description	Unprovide a retailer's customer account
HTTP Method	DELETE
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}
JSON request (example)	none
JSON response (example)	Click here to expand... { "Code":0, "Description":"Ok" }
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.

Add the package to the retailer's customer account

Method to add packages to the selected account.

	Required	Where	Description
id_Account	X	URL	See activation status response
id_Pack	X	URL	See get packages
Quantity	X	Body	Numeric value that depends on WorkMode. Please refer to the row below.
WorkMode	X	Body	Should be "incremental" or "absolute" and refers to the way to manage packages. The "incremental" work mode allows the client to add or remove packages as defined by the Quantity field. If a client calls the method 3 times with quantity equals 1, the API method adds 1 package each time. If a client needs to remove a package it calls the method with quantity equals to -1 and the API method removes a package. The "absolute" work mode allows the client to define the total number of packages. If a client calls the method with quantity equals 4, the API method adds 4 packages. If a client needs to remove 2 packages from the current quantity (set to 4 by the previews call) it calls the method with quantity equals 2 and the API method removes 2 packages. NB: "absolute" work mode allows only unsigned value for Quantity.

Description

Add the package to the retailer's customer account

HTTP Method

POST

URL

https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Pack/{id_Pack}

JSON request (example)

Click here to expand...

Incremental:

{
	"Quantity":-3,
	"WorkMode":"incremental"
}

Absolute:

{
	"Quantity":3,
	"WorkMode":"absolute"
}

JSON response (example)

Click here to expand...

{
	"Code":0,
	"Description":"Ok"
}

The resource returns a 200 OK status code if the package was added successfully and the response contains code = 0; if the addition does not end properly, the resource returns a 403 Forbidden and the response contains:

Code	Description	Meaning
1	Quantity limits exceeded	The number of packages you are trying to add/remove exceeds the profile limits
2	Profile rules error	The number of packages you are trying to add/remove exceeds some profile rule limit (for example, you cannot remove a package related to SMS)
3	Invalid quantity	This error condition appears when the work mode equals “absolute” and the quantity value is negative
4	Invalid work mode	The WorkMode field should be “incremental” or “absolute” ONLY

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	Invalid ExternalUserId.

Note

It is impossible to remove packages from the TRIAL profile
It is impossible to remove credits-related packages

Get retailer's customer account logins

The resource allows retrieving the logins available for this account/console. It is necessary if the retailer allows his customers to add more administrators to an account.

	Required	Where	Description
id_Account	X	URL	See activation status response

Description	Unprovide a retailer's customer account
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Login
JSON request (example)	none
JSON response (example)	Click here to expand... { "IsPaginated":false, "Items":[ { "IdLogin":45792, "Username":"user1" }, { "IdLogin":45793, "Username":"user2" }], "PageNumber":0, "PageSize":20, "Skipped":0, "TotalElementsCount":2 }
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.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.

Get retailer's customer account login URL

The method provides the URL to log in to the account.

	Required	Where	Description
id_Account	X	URL	See activation status response
id_Login	X	URL	See get logins response

Description	Get retailer's customer account login URL
HTTP Method	GET
URL	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Login/{id_Login}
JSON request (example)	none
JSON response (example)	Click here to expand... "http:\/\/mailup_trial.mailadmin.io\/Console\/Login.aspx?Code=2f3g3m0G2K3L1B242A1f412E0a2118373c1T1f0e1F39452a373z2P2h0n0Z3L3a2j3H2707350C3j030L3Y0O3t1A2y4032373Q3c0S2O3F1I343I0g3O0b3d050L1m-1r2K1C01041D3F013e2A0E1X3b1T3a0W1H4128020k0z0R180P053b3j1r3G152C"
Paging and filtering (example)	none

Errors

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
400 BadRequest	ExternalUserId validation fails	Invalid ExternalUserId.