XML Subscription API

This article describes how to add subscribers using XML.

Adding a Subscriber

The following XML wireframe can be posted to https://[domain]/xml/subscription_import/ where [domain] is the relevant masked domain (i.e. www.mydigitalpublication.com):

If you'd like to use a secure connection and you don't have an SSL certificate for your masked domain, you can use https://mydigitalpublication.com. In this case please be sure to specify your actual host domain using the <host> attribute.

<subscription_import user="publisher_login" pass="publisher_pass" method="insert" subscription_id='subscription_id'>
  <subscriber>
    <email>fred@bedrock.com</email>
    <issue_id>3570</issue_id>
    <host>mydigitalpublication.com</host>
    <fname>First</fname>
    <lname>Last</lname>
    <city>City</city>
    <state>State/Province</state>
    <country>Country</country>
    <zip>Postal Code</zip>
    <address>Address</address>
    <address2>Address line 2</address2>
    <phone>+1-407-555-1212</phone>
    <fax>+1-407-555-1212</fax>
    <begindate>2008-08-05</begindate>
    <expiration>0000-00-00</expiration>
    <login>Login_Name</login>
    <password>passphrase</password>
    <company>My Company</company>
    <hearfrom>Google</hearfrom>
  </subscriber>
</subscription_import>

Let's go through each attribute:

<subscription_import user="publisher_login" pass="publisher_pass" method="insert" subscription_id='subscription_id'>

The subscription_id can be found by hovering over the "+" sign for the subscription in the Subscriptions/Readers page and looking at your browser status bar at the bottom left of your browser. The subscription_id will be the number in parenthesis.

<subscriber>

There will be one <subscriber> attribute for each subscriber you'd like to add.

<email>fred@bedrock.com</email>

Email address of the subscriber. This is required. This is also the login and password if they are not not filled in.

<issue_id>3570</issue_id>

This can either be a specific issue id for single issue sales, or just an issue id that is covered by the subscription id above. The issue id can be found in the dashboard under Distribution Links -> Digital Edition -> This Issue as the number after "i=". You can also get a list of current issues for your publication from the archive XML feed at https://[domain]/publication/archive.php?id_publication=99999, where id_publication is the publication id. Go here for the complete documentation on archive.php.

<host>www.mydigitalpublication.com</host>

The host name that you're using for the publication. This is required.

<fname>First</fname>
<lname>Last</lname>
<city>City</city>
<state>State/Province</state>
<country>Country</country>
<zip>Postal Code</zip>
<address>Address</address>
<address2>Address line 2</address2>
<phone>+1-407-555-1212</phone>
<fax>+1-407-555-1212</fax>

Name, address, and phone numbers for the subscriber. These fields are optional.

<begindate>2008-08-05</begindate>
<expiration>0000-00-00</expiration>

The start and end dates of the subscription. These are required. An expiration of 0000-00-00 means the subscription never expires.

<login>Login_Name1</login>

If the email address is intended to be the login then do not include the <login> attribute. <login> or <email> are required, but both can be filled independently.

<password>passphrase</password> - This field must be filled when creating a record but
                                  can be left out when updating a record.
<company>My Company</company> - This field is optional.
<hearfrom>Google</hearfrom> - This field is optional. 

We will reply with the following:

<import_response>

You'll then get one of these for each subscriber you sent.

<subscriber>
  <email>fred@bedrock.com</email>
  <subscriber_id>718842</subscriber_id>

The <subscriber_id> is our internal subscriber id for this subscriber.

  <start_date>2008-08-05</start_date>
  <end_date>0000-00-00</end_date>
  <url>http://www.mydigitalpublication.com/reports/rissue.php?s=123456&amp;r=718843&amp;i=13507</url>
  <auto_login_url>http://www.mydigitalpublication.com/publication/logincheck.php</auto_login_url>
  <auto_login_post_string>reader_login=fred@bedrock.com&amp;reader_password=passphrase&amp;i=3570&amp;pub_id=1960</auto_login_post_string>

The pub_id is the publisher ID.

Posting the URL contained in <url> to the URL will allow the first person to click on it access to the publication without having to login. Posting the string contained in <auto_login_post_string> to the URL contained in <auto_login_url> will allow automatically log in the reader each time they access that URL. Both options will set also set a cookie. Note here that the “&amp;” portions of the string are just XML encoded. The string <auto_login_post_string> in the sample above, once decoded, will be "reader_login=fred@bedrock.com&reader_password=passphrase&i=3570&pub_id=1960".

PLEASE NOTE: it is never appropriate to send the <auto_login_url> and <auto_login_post_string> directly to the browser of a reader/subscriber.

</subscriber>
<import_status>granted</import_status>

The import status. In this case it was successful.

</import_response>

End of </import_response> attribute.

If something required is missing, you'll get an <error> tag with a human readable description of what went wrong.

The <url> tag in the response contains a "magic link". This link will allow the first person who views it to access the publication referenced without having to login. The next person (or even the same person in a different browser or after clearing cookies) who uses that link will be forced to login. We use these links for emails we send out to known subscribers.

Updating a Subscriber

The process for Adding a Subscriber can also be used to update a subscriber's information. The key field is <email>, so any post after the initial one will update the record with the matching email address.

Using a "Redirected URL"

The same function accomplished by posting XML as described above may also be accomplished for single subscriber logins by POSTING or GETTING a "Redirected URL". The same process applies as above, but a standard POST or GET is used instead of using an XML POST.

For example:

https://www.mydigitalpublication.com/xml/subscription_import/?user=publisher_login&pass=publisher_pass&method=insert&subscription_id=subscription_id&email=fred@bedrock.com&issue_id=3570

This URL can accept the following parameters:

user (The publisher's login)
pass (The publisher's password)
method (value will always be "insert")
subscription_id
issue_id
host
fname
lname
company
city
state
country
zip
address
address2
email
phone (+1-407-555-1212)
fax (+1-407-555-1212)
begindate (YYYY-MM-DD)
expiration (YYYY-MM-DD)
login (Subscriber's login, if not specified defaults to subscriber's email address)
password (Subscriber's password, if not specified defaults to subscriber's email address)