Examples

In order to get you started with using the API, we have collected some examples in a couple of different languages for you.

Python

Python really shines when it comes to XML-RPC support. The standard library has the excellent xmlrpclib bundled and it will work perfectly with the Ubivox API.

Helpful links for Python

Python Library Documentation for xmlrpclib:

http://docs.python.org/library/xmlrpclib.html

Python Module of the Week: xmlrpclib:

http://www.doughellmann.com/PyMOTW/xmlrpclib/

Creating a new subscription

from xmlrpclib import ServerProxy

server = ServerProxy("https://username:password@company.clients.ubivox.com/xmlrpc/")

# Using opt-in to list ID 42 for user@example.com
server.ubivox.create_subscription("user@example.com", [42], True)

# Not using opt-in to list ID 42 for user@example.com
server.ubivox.create_subscription("user@example.com", [42], False)

# Not using opt-in to list ID 42 and 60 for user@example.com
server.ubivox.create_subscription("user@example.com", [42, 60], False)

Updating subscriber data

from xmlrpclib import ServerProxy

server = ServerProxy("https://username:password@company.clients.ubivox.com/xmlrpc/")

# Set the data field Name for user@example.com
server.ubivox.set_subscriber_data("user@example.com", {"Name": "John Doe"})

Unsubscribing

from xmlrpclib import ServerProxy

server = ServerProxy("https://username:password@company.clients.ubivox.com/xmlrpc/")

# Cancel a subscription to list ID 42 for user@example.com
server.ubivox.cancel_subscription("user@example.com", [42])

# Cancel a subscription to list ID 42 and 60 for user@example.com
server.ubivox.cancel_subscription("user@example.com", [42, 60])

Create and send a delivery

import datetime

from xmlrpclib import ServerProxy

server = ServerProxy("https://username:password@company.clients.ubivox.com/xmlrpc/")

# Create a new delivery on list ID 42
delivery_id = server.ubivox.create_delivery(
    "My first newsletter", 
    "HTML body", 
    "Text body", 
    42
)

# Schedule the delivery for delivery ASAP
now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
server.ubivox.send_delivery(delivery_id, now)

Error/Exception handling

from xmlrpclib import ServerProxy, Fault

server = ServerProxy("https://username:password@company.clients.ubivox.com/xmlrpc/")

try:

    # Using opt-in to list ID 42 for user@example.com
    server.ubivox.create_subscription("user@example.com", [42], True)

except Fault, e:

    # You can use your own error message, by checking the e.faultCode parameter

    if e.faultCode == 1003:
        print "You are already subscribed"

    # Or use the one Ubivox supplies for you, available in e.faultString

    print e.faultString

    # This will print "The user is already subscribed" if that was the error.

else:

    # No exception happened: Everything went well!

    print "You are now subscribed."

PHP

Our PHP examples utilize Zend‘s framework to communicate with the Ubivox API. This framework handles most of the tedious work of connecting and sending method calls.

Helpful links for Zend and PHP

Download Zend’s framework - choose Minimal unless you need other parts of the framework:

http://framework.zend.com/download/latest

Initial setup and connection - init.php

<?php

// Set the include path to point to your Zend framework folder
set_include_path('/path/to/ZendFramework-minimal/library/');
 
require_once('Zend/Loader/Autoloader.php'); 

// Initiate the Zend Autoloader. This will load the necessary
// modules when they are initiated.
Zend_Loader_Autoloader::getInstance();

try {

  // Initiate the Zend Client - remember to replace the hostname with your host
  $http = new Zend_Http_Client('https://company.clients.ubivox.com/xmlrpc/', 
                               array('keepalive'=>true)); 

  // Setting the authentication used to connect to the Ubivox API
  $http->setAuth('API username', 'API password', Zend_Http_Client::AUTH_BASIC);

  $client = new Zend_XmlRpc_Client('https://company.clients.ubivox.com/xmlrpc/', $http);

  // You now have a connection to the Ubivox API and method calls can be sent

} catch(Zend_XmlRpc_Client_HttpException $e) {
 
  // Connection error
  print 'Could not connect: '.$e->getMessage();
 
}

?>

Creating a new subscription

<?php

include('init.php');

// Using opt-in to list ID 42 for user@example.com
$client->call('ubivox.create_subscription', 
              array('user@example.com', 42, 1));
 
// Not using opt-in to list ID 42 for user@example.com
$client->call('ubivox.create_subscription', 
              array('user@example.com', 42, 0));

// Not using opt-in to list ID 42 and 60 for user@example.com
$client->call('ubivox.create_subscription', 
              array('user@example.com', array(42, 60), 0));

?>

Updating subscriber data

<?php

include('init.php');

// Set the data field Name for user@example.com
$client->call('ubivox.set_subscriber_data', 
              array('user@example.com', array("Name" => "John Doe")));

?>

Unsubscribing

<?php

include('init.php');

// Cancel a subscription to list ID 42 for user@example.com
$client->call('ubivox.cancel_subscription', 
              array('user@example.com', 42));

// Cancel a subscription to list ID 42 and 60 for user@example.com
$client->call('ubivox.cancel_subscription', 
              array('user@example.com', array(42, 60)));

?>

Create and send a delivery

<?php

include('init.php');

// Create a new delivery on list ID 42
$delivery_id = $client->call('ubivox.create_delivery', 
                             array('My first newsletter', 
                                   'HTML body', 
                                   'Text body', 
                                   42));

// Schedule the delivery for delivery ASAP
$now = date('Y-m-d H:i:s');
$client->call('ubivox.send_delivery', 
              array($delivery_id, $now));

?>

Error/Exception handling

<?php

include('init.php');

try {
 
  // Using opt-in to list ID 42 for user@example.com  
  $client->call('ubivox.create_subscription', 
                array('user@example.com', 42, 1));
 
} catch(Zend_XmlRpc_Client_FaultException $e) {

  // You can use your own error message, by checking the $e->getCode() parameter
  if ($e->getCode() == 1003) {
  	print "You are already subscribed";
  }

  // Or use the one Ubivox supplies for you, available in $e->getMessage()
  print $e->getMessage();

  // This will print "The user is already subscribed" if that was the error.

}
 
// No exception happened: Everything went well!
print "You are now subscribed.";

?>