Public SmartSubscribe Service

Using the public SmartSubscribe API is simple. Customers can only use GET requests to receive information about a specific resource. The kind of information and the resource they are seeking is contained in the URL.

To provide a practical example we use famous the command-line utility curl to access a SmartSubscribe API:

curl -G -basic -u testuser:testuser http://testserver.xq/svc/address/role/foo@bar.com

This call contains all elements that must be present for a successfull call to a protected Smartsubscribe API:

  1. “-G”: we use a GET request, the one that is also used to load web pages. That makes it also possible to access our APIs with a web browser
  2. “-basic”: this specifies that the call will use HTTP Basic authentication. HTTP Basic uses a user name/password combination for authentication without encryption.
  3. “-u testuser:testuser”: the user name and the password required by HTTP Basic authentication
  4. the url “http://…/svc/address/role/foo@bar.com”
    1. svc: we want to access a full, protected service
    2. address: we need information about an e-mail address
    3. role: we want to know about the role aspect of the address
    4. the actual resource, the address foo@bar.com is the last part of the URL

Of course, if we wanted to access a free service, the authentication part wouldn’t be necessary:

curl -G http://testserver.xq/trial/address/role/foo@bar.com

Here we just have to specify the GET operation and the resource.

By default the caller will get an answer in XML format, something like

<roleStatus>
    <result>1</result>
</roleStatus>

SmartSubscribe can answer in XML or JSON. To specify a format the call must include a standard HTTP Accept header with application/json for JSON or application/xml for XML. An API call with a JSON specification would look like this:

curl -G -basic -u testuser:testuser -H'Accept: application/json' http://testserver.xq/svc/address/role/foo@bar.com

The only differnce to first call is the Accept header -H’Accept: application/json‘. This header is a standard HTTP header, which is also used by web browsers. In this case the answer would be something like

{"result": 1}

The caller should also check the status code for each API call. Normally successful calls will end with the 200 OK response code. See the individual service descriptions for alternative responses.

Internationalized domains, non-ASCII addresses

If information about international addresses or domains, with non-ASCII characters, is required, the resource, the address must be percent-encoded.

Example: when requesting information about an address from German umlaut domain, info@blümchen.de, the direct approach

curl -G -basic -u testuser:testuser http://testserver.xq/svc/address/role/info@blümchen.de

would be illegal. Non-ASCII characters are not allowed in URLs. Instead use percent-encoding to create a valid URL:

curl -G -basic -u testuser:testuser http://testserver.xq/svc/address/role/info@bl%C3%BCmchen.de

Please note that all ADC services except the Quality and the Syntax check expect ASCII addresses as inputs. Please use the mentioned services as entry points to decode possible Unicode addresses, before calling the other services.