/
Self provisioning - retailers only

Self provisioning - retailers only

Nov 17, 2021



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)





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



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)







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

HTTP Status Code

When

Message

403 Forbidden

Unexisting id_profile

You cannot access the provided profile.

id_profile not assigned to a specified Retailer account

Note

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



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)







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







Paging and filtering (example)

none

Errors

HTTP Status Code

When

Message

HTTP Status Code

When

Message

403 Forbidden

Unexisting id_profile

You cannot access the provided profile.

id_profile not assigned to specified IdConsoleRetailer

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



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)





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





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

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

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

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



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)



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

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

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



Required

Where

Description

id_Account

X

URL

See activation status response

id_Profile

X

URL

See get profiles



Description