Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 20 Next »

On this page:

 

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.

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:

 RequiredWhereDescription
id_ProfileXURLSee 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 CodeWhenMessage
403 ForbiddenUnexisting id_profileYou cannot access to provided profile.
id_profile not assigned to specified Retailer account

Note

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

Get the available languages by 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

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 CodeWhenMessage
403 ForbiddenUnexisting id_profileYou 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.

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 the access if:

  • AccessToken contains an empty ExternalUserId
  • AccessToken contains an ExternalUserId that hasn't got the the right scope to perform 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:

 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 respondes, your clients has to poll the activation status method to understand when the creation process ends. The response could contains domains that should be redirect 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 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 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

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

Get reseller's customer account profile activation status

Http verbGET
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
 RequiredWhere
id_ActivationXURL
Request ADM
 RequiredWhoWhere
id_ActivationXGiven by ResellerRequest 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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails
id_Activation is not a numberInvalid activation.

 

Change reseller's customer account profile

Http verbPUT
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
 RequiredWhere
id_AccountXURL
id_ProfileXURL
Request ADM
 RequiredWhoWhere
id_AccountXGiven by ResellerRequest API
id_ProfileXGiven by ResellerRequest 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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails


Disable reseller's customer account info

Http verbPUT
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
 RequiredWhere
id_AccountXURL
Enable Querystring
Request ADMNone
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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

Enable reseller's customer account info

Http verbPUT
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
 RequiredWhere
id_AccountXURL
Enable XQuerystring
Request ADMNone
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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails


Unprovide reseller's customer account

Http verbDELETE
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
 RequiredWhere
id_AccountXURL
Request ADMTBD
Return valueThe resource returns a 200 OK status code.

WHEN REQUESTS FAIL:

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

Get reseller's customer account status

Http verbGET
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
 RequiredWhere
id_AccountXURL
Request ADMTBD
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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails
403 ForbiddenInvalid Id_AccountYou cannot access to 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)


Add package to reseller's customer account

Http verbPOST
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
 RequiredWhere
id_AccountXURL
id_PackXURL
QuantityXBody
WorkModeXBody

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
 RequiredWhoWhere
id_AccountXGiven by ResellerRequest API
id_PackXGiven by ResellerRequest 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 CodeWhenMessage
400 BadRequestIdPack is not numericInvalid pack.
ExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

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

  1. Non si possono  aggiungere/rimuovere pacchetti ad un profilo TRIAL
  2. Non di possono rimuovere pacchetti a consumo dai profili Economy e Premium
  3. 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.
  4. 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 verbGET
Resource URLAccount/{id_Account}/Login
Request API
 RequiredWhere
id_AccountXURL
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 CodeWhenMessage
400 BadRequestExternalUserId empty.Invalid ExternalUserId.
ExternalUserId validation fails

Get reseller's customer account login url

Http verbGET
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
 RequiredWhere
id_AccountXURL
Request ADM-
Return valueThe reseller's customer account login url string

WHEN REQUESTS FAIL:

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

 

HTTP Method

  • No labels