Retailers

On this page:

Management

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

Note that all management 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... { "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)	https://services.mailup.com/API/v1.1/Rest/RetailerService.svc/Management/Profile?PageSize=2&PageNumber=1

Get retailer-defined packages by 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... { "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)	none

Errors

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

Note

Min e Max equals to the number of packages manageable by selected profile.

Get the available languages by 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... [ "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 to provided profile.
403 Forbidden	id_profile not assigned to specified IdConsoleRetailer	You cannot access to provided profile.

Account

Create a reseller's customer account

Http verb

POST

Resource URL

Account/Activation/Profile/{id_Profile}/Language/{lang}

Request API

	Required	Where
id_Profile	X	URL
lang	X	URL
IpAddress	X	Form request
UserAgent		Form request
Referer		Form request
Email	X	Form request
CustomDomain	X	Form request
CustomSubdomain	X	Form request
ServiceName	X	Form request
ServiceUrl	X	Form request
ServiceLogoutUrl	X	Form request

Request ADM

	Required	Who	Where
ExternalUserId	X	AuthorizationCode	Authorization Flow
IdAnagrafica	X	IdAnagrafica field of Newsletter table where id = DeveloperId of APIConsumerApplication	Database
IdProfilo	X	Given by Reseller	Request API
IP	X	Given by Reseller	Request API
UserAgent		Given by Reseller	Request API
Referer		Given by Reseller	Request API
Email	X	Given by Reseller	Request API
Lang	X	Given by Reseller	Request API
CustomDomain	X	Given by Reseller	Request API

Return value

An object containing these fields:

id_Activation
Hash
Code
Description
ControlPanelDomain
LinkTrackingDomain
ImageTrackingDomain.

Code and description return these values:

Code: -1, Description: Unknown account activation status
Code: 0, Description: Ok
Code: 1, Description: Processing
Code: 2, Description: Error
Code: 3, Description: Language 'XX' is not available for profile YY.
Code: 4, Description: IpAddress cannot be null, empty or invalid.
Code: 5, Description: Email cannot be null, empty or invalid.
Code: 6, Description: Domains cannot be null, empty or invalid.
Code: 7, Description: Custom domain not available.
Code: 8, Description: Link tracking domain not available
Code: 9, Description: Image tracking domain not available
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.

WHEN REQUESTS RUN:

ExternalUserId, id_Profile, lang, IpAddress, Email, ServiceName, ServiceUrl, ServiceLogoutUrl CustomSubdomain and CustomDomain MUST HAVE a value
UserAgent and Referer could be empty

WHEN REQUESTS FAIL:

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 to provided 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.
	CustomDomain is null, empty or invalid	Code: 6 Description: Custom domain cannot be null, empty or invalid.
	Custom domain not available	Code = 7; Description = Custom domain not available.
	ADM service checks the value is not allowed for reseller's editions	Code: 3 Description: Language '{lang}' is not available for profile {id_Profile}.

NOTE:

E' possibile creare UN SOLO account TRIAL per ExternalUserId. Se si cerca di creare un account trial utilizzando un ExternalUserId già utilizzato, la risposta conterrà Code: 1, Description: Processing fino a che il primo account non è stato creato, ed al termine della sua creazione conterrà Code: 2, Description: Error.
E' possibile creare PIU' account ECONOMY o PREMIUM per ExternalUserId. Se si cerca di creare un account economy o premium utilizzando un ExternalUserId già utilizzato, la risposta conterrà Code: 1, Description: Processing fino a che il primo account non è stato creato, ed al termine della sua creazione conterrà Code: 0, Description: Ok.

Get reseller's customer account profile activation status

Http verb

GET

Resource URL

Account/Activation/{id_Activation}/Status

NOTE: the id_Activation is the value returned with Create a reseller's customer account resource

Request API

	Required	Where
id_Activation	X	URL

Request ADM

	Required	Who	Where
id_Activation	X	Given by Reseller	Request API

Return value

An object (like ConsoleActivationStatusResponse object for PublicService) containing:

Code (0: Ok, 1: Processing, 2: Error, 3: An error occurred finalizing account creation)
Description (Ok, Processing, Error, An error occurred finalizing account creation)
IdAccount

NOTE: the IdAccount field contains a value ONLY when the reseller's customer console is propertly created, so Code field contains the OK-CREATED code value.

NOTE2: the IdAccount equals to ConsoleId

WHEN REQUESTS RUN:

ExternalUserId and id_Activation MUST HAVE a value
id_Activation MUST be a numeric value

WHEN REQUESTS FAIL:

HTTP Status Code	When	Message
400 BadRequest	ExternalUserId empty.	Invalid ExternalUserId.
	ExternalUserId validation fails	Invalid ExternalUserId.
	id_Activation is not a number	Invalid activation.

Change reseller's customer account profile

Http verb

PUT

Resource URL

Account/{id_Account}/Profile/{id_Profile}

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL
id_Profile	X	URL

Request ADM

	Required	Who	Where
id_Account	X	Given by Reseller	Request API
id_Profile	X	Given by Reseller	Request API

Return value

-

NOTE: the return value is the HTTP Status code of the response. ADM executes this operation asynchronously. Every time the reseller invokes the resource, ADM 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.

NOTE 2: the reseller can invoke the resource as many times as it wants.

WHEN REQUESTS FAIL:

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

Disable reseller's customer account info

Http verb

PUT

Resource URL

Account/{id_Account} or Account/{id_Account}?Enable=false

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL
Enable		Querystring

Request ADM

None

Return value

The resource returns a 200 OK status code and and object containing account status properties.

In detail the returned object actually contains:

- Code: int value corresponding to the account status code
  - 0: Active
  - 1: Deactivated
- Description: human readable description of the account status code
  - Active
  - Deactivated
- ValidFrom: String corresponding to the validity start date
- ValidTo: String corresponding to the validity end date

WHEN REQUESTS FAIL:

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

Enable reseller's customer account info

Http verb

PUT

Resource URL

Account/{id_Account} or Account/{id_Account}?Enable=true

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL
Enable	X	Querystring

Request ADM

None

Return value

The resource returns a 200 OK status code and and object containing account status properties.

In detail the returned object actually contains:

Code: int value corresponding to the account status code
- 0: Active
- 1: Deactivated
Description: human readable description of the account status code
- Active
- Deactivated
ValidFrom: String corresponding to the validity start date
ValidTo: String corresponding to the validity end date

WHEN REQUESTS FAIL:

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

Unprovide reseller's customer account

Http verb

DELETE

Resource URL

Account/{id_Account}

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL

Request ADM

TBD

Return value

The resource returns a 200 OK status code.

WHEN REQUESTS FAIL:

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

Get reseller's customer account status

Http verb

GET

Resource URL

Account/{id_Account}/Status

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL

Request ADM

TBD

Return value

An object contains these fields:

Code (numeric)
- 0: Enabled
- 1: Disabled
- 2: Unprovided
- -1: Error or Processing
Description (string)
- Enabled
- Disabled
- Unprovided
- Error or Processing
ValidFrom (string, it's a DateTime)
ValidTo (string, it's a DateTime)
IdAccount
Credits
ActivePacks
- Id
- Quantity
- CurrentQuantity

WHEN REQUESTS FAIL:

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

Add package to reseller's customer account

Http verb

POST

Resource URL

Account/{id_Account}/Pack/{id_Pack}

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL
id_Pack	X	URL
Quantity	X	Body
WorkMode	X	Body

WorkMode should be "incremental" or "absolute" and refers to the way to manage packages.

The "incremental" work mode allows client to add or remove packages as defined by Quantity field. If client calls the method 3 times with quantity equals to 1, API method adds 1 package each time. If client needs to remove a package it calls the method with quantity equals to -1 and API method removes a package.

The "absolute" work mode allows client to define the total number of packages.If client calls the method with quantity equals to 4, API method adds 4 packages. If 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.

Request ADM

	Required	Who	Where
id_Account	X	Given by Reseller	Request API
id_Pack	X	Given by Reseller	Request API

Return value

In detail the returned object actually contains:

Code: int value corresponding to the account status code
- 0: Ok
- 1: Quantity_limits_exceeded
- 2: Profile_rules_error
- 3: Invalid_quantity
- 4: Invalid_workmode
Description: human readable description of the account status code
- Ok
- Quantity limits exceeded
- Profile rules error
- Invalid quantity
- Invalid workmode

NOTE: the resource returns a 200 OK status code if the package was added succesfully and the response contains code = 0; if the addition does not end propertly, the resource returns a 403 Forbidden and the response contains code = 1

WHEN REQUESTS RUN:

the response contains an object with:
- Code = 0
- Description = Ok

WHEN REQUESTS FAIL:

HTTP Status Code	When	Message
400 BadRequest	IdPack is not numeric	Invalid pack.
	ExternalUserId empty.	Invalid ExternalUserId.
	ExternalUserId validation fails	Invalid ExternalUserId.
403 Forbidden	The package cannot be added	the response contains an object with: Code = 1 Description = Quantity limits exceeded oppure Code = 2 Description = Profile Rules Error

NOTE

Non si possono aggiungere/rimuovere pacchetti ad un profilo TRIAL
Non di possono rimuovere pacchetti a consumo dai profili Economy e Premium
La tabella RetailerProfilePack definisce il numero di pacchetti Massimo e Minimo previsti per il profilo. La visibilità del pacchetto per l'utente finale (e quindi la sua attivabilità) è gestita con il campo IsActivable.
Nel caso la risposta abbia lo status code settato a 403 Forbidden si ottiene la risposta con Code=1 quando la richiesta non viene validata dai limiti previsti dalla tabella RetailerProfilePack, mentre Code=2 quando la validazione secondo i limiti della tabella retailerProfilePack è ok ma fallisce l'operazione lato ADM. Un caso in cui può essere ritornato Code=2 è quando s cerca di cancellare un pacchetto a consumo (crediti).

Get reseller's customer account logins

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

Http verb

GET

Resource URL

Account/{id_Account}/Login

Request API

	Required	Where
id_Account	X	URL

Request ADM

-

Return value

A list of AccountLogin object containing:

idLogin
Username

NOTE: data come from Newsletters_Login table. idLogin is the id and UserName is the username fields

WHEN REQUESTS FAIL:

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

Get reseller's customer account login url

Http verb

GET

Resource URL

Account/{id_Account}/Login/{id_Login}

NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource

Request API

	Required	Where
id_Account	X	URL

Request ADM

-

Return value

The reseller's customer account login url string

WHEN REQUESTS FAIL:

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

HTTP Method