Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

...

...

...

...

...

...

...

...

...

...


Info

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 in order to ask for enabling your application for account provisioning and to agree on setup details.

 



On this page:

 

Table of Contents

...

Use these methods to retrieve informations pieces of information about your environment (profiles, packages, and languages) and configure your environment.

...

Anchor
GetProfiles
GetProfiles
Get retailer-defined profiles

Description

Get retailer-defined profiles

HTTP Method

GET

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile


JSON request (example)

none

JSON response (example)


Expand


Code Block
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:

    Code Block
    https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile?PageSize=2


  • Retrieving the second page with two items:

    Code Block
    https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile?PageSize=2&PageNumber=1


Anchor
GetPacks
GetPacks
Get retailer-defined packages by profile

To retrieve available languages you need to provide this parameter:

 

RequiredWhereDescription
id_ProfileXURLSee get profile


Description

Get retailer-defined profile-packages relationship

HTTP Method

GET

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Pack


JSON request (example)

none

JSON response (example)


Expand

 

 



Code Block
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:

    Code Block
    https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Pack?PageSize=2


  • Retrieving the second page with two items:

    Code Block
    https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Pack?PageSize=2&PageNumber=1


Errors

HTTP Status CodeWhenMessage
403 ForbiddenUnexisting id_profileYou cannot access
to
the provided profile.
id_profile not assigned to a specified Retailer account

Note

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

...

To retrieve available packages you need to provide this parameter:

...


RequiredWhereDescription
id_ProfileXURLSee get profile


Description

Get the available languages by profile

HTTP Method

GET

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile/{id_Profile}/Lang


JSON request (example)

none

JSON response (example)


Expand

 

 



Code Block
HTTP/1.1 200 OK
 
 [
    "JA",
    "ID",
    "IT",
    "ES",
    "FR",
    "PT",
    "ZH",
    "EN"
  ]

 

 




Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
403 ForbiddenUnexisting id_profileYou cannot access
to
the provided profile.
id_profile not assigned to specified IdConsoleRetailer

Account

 Use these methods to manage retailerretailers' customer's customers accounts. With these methods, you can create new accounts, add or remove packages and get what you need to login 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 forbiddening forbidden the access if:

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

Anchor
CreateAccount
CreateAccount
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:

 

RequiredWhereDescription
id_ProfileXURLSee get profile
langXURLSee get languages
IpAddressXBodyYour client IP address
EmailXBodyYour customer's email address
CustomDomainXBodyYour product or your customer domain
CustomSubdomainXBodyYour product or your customer subdomain to address this service
ServiceNameXBodyYour product name
ServiceUrlXBodyYour product web site
ServiceLogoutUrlXBody

Address to redirect the customer when logouts

UserAgent
 

BodyYour client user agent
Referer
 

BodyYour client referer

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

 


Description

Create a retailer's customer account

HTTP Method

POST

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/Activation/Profile/{id_Profile}/Language/{lang}


JSON request (example)


Expand


Code Block
{
	"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)


Expand


Code Block
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 CodeWhenMessage
400 BadRequestUnexisting 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
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.

Request
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

URL cannot be null, empty, or invalid.

Code: 12;

Description: Service logout

url

URL cannot be null, empty, or invalid.

Note

  1. It is possile possible to create ONLY ONE Trial Control Panels per ExternalUserId. If you try to create more Trial Trials using the same ExternalUserId the response contains Code: 1, Description: Processing until the process ends, and then it contains  Code: 2, Description: Error.
  2. It is possile possible to create MORE non Trial Control Panels per ExternalUserId. If you try to create more non Trial 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.

...

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

 

RequiredWhereDescription
id_ActivationXURLSee create account


Description

Get retailer's customer account profile activation status

HTTP Method

GET

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/Activation/{id_Activation}/Status


JSON request (example)

none

JSON response (example)


Expand
System

The system is creating your new account:

Code Block
HTTP/1.1 201 Accepted
 
{
	"Code":1,
	"Description":"Processing",
	"IdAccount":0
}
 


New account created

succesfully

successfully:

Code Block
HTTP/1.1 200 OK
 
{
	"Code":0,
	"Description":"Ok",
	"IdAccount":23052
}
 

 




Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails
id_Activation is not a numberInvalid 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
URL, or logout
url
URL cannot be set

Code = 3

Description = An error occurred finalizing account creation

Note

  1. the IdAccount field contains a value ONLY when the new account is propertly 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 account profile you have to provide this information:

 

RequiredWhereDescription
id_AccountXURLSee activation status response
id_ProfileXURLSee get profiles


Description

Change retailer’s customer account profile

HTTP Method

PUT

URL


Code Block
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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

403 Forbidden

Invalid id_profile

 


You cannot access

to

the provided profile.

Invalid id_account

You cannot access

to

the provided account.

Note

  1. the return value is the HTTP Status 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 a 202 Accepted status code; otherwise returns a 200 OK status code. If an error occurred it returns 500 Internal Server Error.

  2. 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:

 

RequiredWhereDescription
id_AccountXURLSee activation status response 

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

StatusResponse Code field valueResponse Description field value
Error / Processing-1Error or Processing
Enabled0Enabled
Disabled1Disabled
Unprovided2Unprovided


Description

Get retailer’s customer account status

HTTP Method

GET

URL


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


JSON request (example)

none

JSON response (example)


Expand


Code Block
{
	"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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails
403 ForbiddenInvalid Id_AccountYou cannot access
to
the provided account.

Note

  1. 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).
  2. 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)

...

Method to disable an account.

 

RequiredWhereDescription
id_AccountXURLSee activation status response 
Enable
 

QuerystringCould be FALSE


Description

Disable retailer's customer account

HTTP Method

PUT

URL


Code Block
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)


Expand


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



Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
400 BadRequestExternalUserId 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.

 

RequiredWhereDescription
id_AccountXURLSee activation status response 
EnableXQuerystringMust be TRUE


Description

Enable a disabled retailer's customer account

HTTP Method

PUT

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_account}?Enable=true


JSON request (example)

none

JSON response (example)


Expand


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



Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
400 BadRequestExternalUserId 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.

...


RequiredWhereDescription
id_AccountXURLSee activation status response 


Description

Unprovide a retailer's customer account

HTTP Method

DELETE

URL


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


JSON request (example)

none

JSON response (example)


Expand


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



Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

Add the package to the retailer's customer account

Method to add packages to the selected account.

 

RequiredWhereDescription
id_AccountXURLSee activation status response 
id_PackXURLSee get packages
QuantityXBodyNumeric value that depends on WorkMode. Please
refers
refer to the row below.
WorkModeXBody

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

to

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

to

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

to

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


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


JSON request (example)


Expand

Incremental:

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

Absolute:

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



JSON response (example)


Expand


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

The resource returns a 200 OK status code if the package was added

succesfully

successfully and the response contains code = 0; if the addition does not end

propertly

properly, the resource returns a 403 Forbidden and the response contains:

CodeDescriptionMeaning
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

to

“absolute” and the quantity value is negative

4

Invalid

workmode

work mode

The WorkMode field should be “incremental” or “absolute” ONLY

 

 

 





Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
400 BadRequestIdPack is not numericInvalid pack.
ExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

Note

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

Anchor
GetLogins
GetLogins
Get retailer's customer account logins

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

 

RequiredWhereDescription
id_AccountX

URL

See activation status response 


Description

Unprovide a retailer's customer account

HTTP Method

GET

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Login


JSON request (example)

none

JSON response (example)


Expand


Code Block
{
	"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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

Get retailer's customer account login

...

URL

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

 

RequiredWhereDescription
id_AccountXURLSee activation status response 
id_LoginXURLSee get logins response


Description

Get retailer's customer account login

url

URL

HTTP Method

GET

URL


Code Block
https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Account/{id_Account}/Login/{id_Login}


JSON request (example)

none

JSON response (example)


Expand


Code Block
"http:\/\/mailup_trial.mailadmin.io\/Console\/Login.aspx?Code=2f3g3m0G2K3L1B242A1f412E0a2118373c1T1f0e1F39452a373z2P2h0n0Z3L3a2j3H2707350C3j030L3Y0O3t1A2y4032373Q3c0S2O3F1I343I0g3O0b3d050L1m-1r2K1C01041D3F013e2A0E1X3b1T3a0W1H4128020k0z0R180P053b3j1r3G152C"



Paging and filtering (example)

none

Errors

HTTP Status CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails