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 31 Next »


 

About MailUpImportWS_MailUpImport Methods

Overview

The MailUpImport web service allows you to load into your MailUp account - using groups and lists - contacts coming from your database. It also allows you to retrieve details about lists, groups and status of import operations, and also to segment the database. Among the tasks that you can perform using the MailUpImport Web Service:

  • Get all the distribution Lists and the Groups they contain;
  • Create a new Group within an existing List;
  • Upload a list of subscribers in order to create a new import process;
  • Get import process status;
  • Start import process.

Each method returns a XML string containing a "MailUp Message", which includes a "ReturnCode" and the requested information (when available). 
The ReturnCode is a number, with the following values:

  • < 0 = error code
  • 0 = call successful

Sample ReturnCode

 

<mailupMessage>
<mailupBody>
<ReturnCode>0</ReturnCode>
...
</mailupBody>
</mailupMessage>

Authentication

WS_MailUpImport checks the following parameters in order to authenticate requests:

  • WS username* (predefined for a specific MailUp console)
  • WS password* (to be set in the MailUp console)
  • Sender IP address (third party application)

*different from the credentials used to access the console

Authentication fails if:

  • MailUp API is disabled in your MailUp account;
  • username and/or password are incorrect;
  • the IP address of the third party application has changed since the last successful access. The IP address can be manually changed in the MailUp console.

The WS_MailUpImport web service requires for every call an authentication via username and password; credentials must be passed in the header of the SOAP message.

Sample MailUpImport authentication

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<Authentication xmlns="http://tempuri.org/">
<User>username</User>
<Password>password</Password>
</Authentication>
</soap:Header>
<soap:Body>
...
</soap:Body>
</soap:Envelope>
Security warning: in the current release of the system the credentials passed in the authentication request are not encrypted

 

Error codes

ReturnCode values in case authentication fails are shown below:

Error CodeDescription
-1000unrecognized error
-1001the account is not valid
-1002the password is not valid
-1003suspended account
-1004inactive account
-1005expired account
-1006the web service is not enabled
-1007the web service is not active
-1011IP is not registered
-1012IP is registered but has the "deny access" flag

All the methods requiring idList e listGuid at input, execute a check on the input values and return one of the following:

Error CodeDescription
-100unrecognized error
-101verification failed
-102list Guid format is not valid

 

Glossary

  • MailUp customer: a company/business subscribing to the MailUp service
  • Console URL / NL_URL: MailUp defines a dedicated URL for each Customer. For this reason, external systems must know the exact URL to which to send the request (e.g. http://mailing.myCompany.com/Services/WSMailupImport.asmx). You can use a custom URL if your account has the Private Labeling feature turned on.
  • WS_MailUpImport: a Web Service designed to import recipients from a third party application
  • MailUp API Account: credentials used specifically with the MailUp API, different from the credentials used to log into your MailUp account. They consist of a username and a password. The API account credentials are automatically created when a new MailUp account is created for a new customer, while for existing customers they are manually created via the MailUp console. 
  • WS: Web Service

MailUp API status

Once the API account has been created, the MailUp APIs must be activated in order to be able to receive requests (they are disabled by default for safety reasons): they can be activated manually using the MailUp admin console or automatically by calling a specific URL. Deactivation is also done manually through the MailUp console. The IP address of the application using the web service is registered at activation stage.

To manually activate and configure the MailUp API in your MailUp admin console:

  • Log into your account
  • Navigate to Manage > Web Services
  • Select WSMailUpImport from the drop-down at the top
  • Make sure they are enabled and that the necessary IP addresses have been added to allow for requests coming from there
Here is an example of the settings screen (as of January, 2012).

Note about Data Fields

The WS_MailUpImport methods support up to 20 personal data fields. Should it be necessary to import more than 20 fields, there are other procedures that can be used. For example:

  • Several consecutive calls until all the fields are imported;
  • Batch import from file;
  • Synchronized import from file, using the MailUpSend.SendNewsletterNL web service.

API registration and activation

WS_MailUpImport can be used only after configuring the IP address of the caller. This can be made through the MailUp console or by calling a specific activation method.
The username and password defined for the API account, used to call the web services, are different from those used to access the MailUp console.

Activation via the "Manage" page in the MailUp console

From the menu on the left of the screen in the administration console, select Manage > Web services. The page presents itself as shown in the image below. Inserting an IP address allows to call WS_MailUpImport methods from that very address. All the administration consoles are created with specific username and password for web services: this page also allows to change the password or disable the account.

Activation via call to an URL

A third party application can enable web services via a call to


http://mailing.mycompany/frontend/WSActivation.aspx?usr=<usr>&pwd=<pwd>&nl_url=<nl_url>&ws_name=<ws_name>


MailUp provides an ASP.NET Web Form to allow third party applications to activate (if not already active) and register (store) the IP address of the caller. The form supports the parameters described below, both in GET and in POST modes:

  • usr: MailUp API Account username (e.g. a7132)
  • pwd: MailUp API Account password
  • nl_url: Console URL (e.g abcd.sp09.com, omitting "http://" )
  • ws_name: Web service name (specify: "WSMailUpImport")


MailUp web services register the IP address of the computer calling, and therefore support calls to web services for that specific console, only if coming from that very address. If the caller's IP address changes, WSActivation web service must be called again.

Sample WSActivation response

 

1
2
3
4
5
6
7
8
9
10
<mailupMessage>
<mailupBody>
<ReturnCode>0</ReturnCode>
<WS_Activation>
<WS_Name> WS_MailUpImport </WS_Name>
<DateOfRequest>2008-01-16</DateOfRequest>
<User>admin</User>
</WS_Activation>
</mailupBody>
</mailupMessage >

ReturnCodes

CodeDescription
0request execution succeeded
-2ws name has not been specified (1)
-4user name has not been specified (1)
-8password has not been specified (1)
-16nl url has not been specified (1)
-1000unrecognized error
-1001the account is not valid
-1002the password is not valid
-1003suspended account
-1004inactive account
-1005expired account
-1006the web service is not enabled
-1007the web service is not active
-1008the web service is already active
-1009web service activation error
-1010IP registration error

 

(1) ReturnCode can be a combination of these







  • No labels