Account provisioning: activating a MailUp account via API

Problem

Applications that integrate with MailUp may wish to request new MailUp accounts if the user of the application is not yet a MailUp user.

Solution

You can build the ability to activate a new MailUp account right into your application by using the MailUp public API endpoint. Below you can find the expected workflow and the technical details for implementing it. An example of an application using the MailUp account provisioning API is the APS package. Below we describe how to activate a free trial account, but the same methods can be used - upon request - to provide custom setups (ie Whitelabel platform with custom features enabled). 

Workflow

1. The external application requests account activation using the TrialActivation method and specifying an email address that has already been confirmed (i.e. there is no need for an additional email that confirms that the email address is valid)

2. Activation starts and the TrialActivationStatus method can be used to get activation status. When activation is in progress, TrialActivationStatus returns a value that is different than 2. While status is different than 2 the external application is not yet able to connect to the console account, the following strings could be displayed:

   1. Value = 3,4 or 6 => “An error happened, the activation will be managed directly by MailUp support”. This result rarely happened during maintenance activities, in which processing was suspended for about 2 hours and then restarted.

   2. Value = 5 or 7 => ”The trial activation is in progress, you’ll receive the account credential soon.”

3. When activation is completed you’ll receive MailUp account credentials in your inbox and, at the same time,  TrialActivationStatus returns 2.

4. At this point, the MailUp account is available, and received credentials can be inserted into the external application to perform authentication on the newly activated account

Different authentication & authorization

Access to the resources (lists, messages, subscribers) of the newly activated account requires an authentication and authorization process that is different than the one used for the trial account activation methods: specifically, it requires OAuth2 authentication with a token that has to be periodically refreshed when HTTP 401 error is returned. Please refer to "Samples and Wrappers" if you need a working example of an application that properly uses the refresh token to access to MailUp resources. See more information about authorization and authentication in the REST API.

Getting Started

• Register your application to get your API keys (link). 

• Contact MailUp Support and ask for enabling your application to use the account provisioning feature. 

• Your request will be reviewed and, in case of success, your application will be authorized to create new MailUp trial accounts

How to activate a trial account

• POST callback URL: https://services.mailup.com/API/v1.1/Rest/PublicService.svc/Console/TrialActivation 

• Arguments :
  
  
  

1.  

   1. Arguments can be sent as XML or JSON according to the user-defined value set in the header (http://help.mailup.com/display/mailupapi/Resource+access+data+format)

   2. Arguments and their meaning can be explained as follows :

•  

  • Method callback must be enclosing the API KEY in the header as stated on this page (Please see "Resource Access Requirements")
    [Authorization] = "Basic " + Base64(ClientId + ":" + ClientSecret)

  • Callback response returns an Identity (ID) that can be used to track activation status with a further callback to the following https://services.mailup.com/API/v1.1/Rest/PublicService.svc/Console/TrialActivationStatus. (TrialActivationStatus)

  • Returned codes from TrialActivationStatus are:

    1 – Confirmed (Request has been accepted, activation is ready to start) 2 – Processed (Your trial has been activated and you’ll receive the account credentials in your inbox) 3 – Error (An error occurred and an alert has been notified to our support team in order to solve this issue) 4 – Manual (MailUp platform is in maintenance mode, your request will be processed as soon as the platform will be restored) 5 – In progress (The trial activation is in progress, soon you’ll receive the account credentials) 6 – Blocked (An error occurred and an alert has been notified to our support team in order to solve this issue) 7 – Re elaborated (The trial activation is in progress, soon you’ll receive the account credentials)

     

  • Any activation request can be performed with a single call to TrialActivation  and further callbacks looping on TrialActivationStatus until it returns ID=2
    
    
    
    

•  

  • Creating a new account may take up to a couple of minutes. When completed, the activation process will take care of sending activation confirmation message and login credentials to the applicant’s defined email address

  • Login credentials can be only transmitted by email as no API method can return those values.

  • Currently, there’s no way to retrieve the list of the accounts activated by a certain application.