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 Examples¶

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 Examples¶

Our PHP examples utilize our Ubivox API PHP client to communicate with the Ubivox API.

More information about our PHP client

Our client is hosted in Bitbucket, where you can download and report bugs as well:: https://bitbucket.org/ubivox/ubivox-api-php

Creating a new subscription¶

<?php

require_once "ubivox_api.php";

$client = new UbivoxAPI(
    "username", 
    "password", 
    "https://company.clients.ubivox.com/xmlrpc/"
);

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

// 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), false));

?>

Updating subscriber data¶

<?php

require_once "ubivox_api.php";

$client = new UbivoxAPI(
    "username", 
    "password", 
    "https://company.clients.ubivox.com/xmlrpc/"
);

// 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

require_once "ubivox_api.php";

$client = new UbivoxAPI(
    "username", 
    "password", 
    "https://company.clients.ubivox.com/xmlrpc/"
);

// 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

require_once "ubivox_api.php";

$client = new UbivoxAPI(
    "username", 
    "password", 
    "https://company.clients.ubivox.com/xmlrpc/"
);

// 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

require_once "ubivox_api.php";

$client = new UbivoxAPI(
    "username", 
    "password", 
    "https://company.clients.ubivox.com/xmlrpc/"
);

try {
 
  // Using opt-in to list ID 42 for user@example.com  
  $client->call("ubivox.create_subscription", 
                array("user@example.com", 42, 1));
 
} catch(UbivoxAPIError $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.";

?>

Node.js Examples¶

The Node.js examples here use the xmlrpc NPM package:

Links for using XML-RPC with Node.js

The xmlrpc NPM package: https://www.npmjs.com/package/xmlrpc
How to use NPM to install the xmlrpc package: https://www.npmjs.com/package/xmlrpc/tutorial
The moment NPM package for date/time handling: https://www.npmjs.com/package/moment

Creating a new subscription¶

var xmlrpc = require("xmlrpc");

var client = xmlrpc.createSecureClient({ 
    host: "company.clients.ubivox.com",
    path: "/xmlrpc/",
    basic_auth: {
        user: "username",
        pass: "password"
    }
});

// Using opt-in to list ID 42 for user@example.com
client.methodCall(
    "ubivox.create_subscription", 
    ["user@example.com", 42, true], 
    function (error, value) {
        if (error) throw error;
    }
);

// Not using opt-in to list ID 42 for user@example.com
client.methodCall(
    "ubivox.create_subscription", 
    ["user@example.com", 42, false], 
    function (error, value) {
        if (error) throw error;
    }
);

// Not using opt-in to list ID 42 and 60 for user@example.com
client.methodCall(
    "ubivox.create_subscription", 
    ["user@example.com", [42, 60], false], 
    function (error, value) {
        if (error) throw error;
    }
);

Updating subscriber data¶

var xmlrpc = require("xmlrpc");

var client = xmlrpc.createSecureClient({ 
    host: "company.clients.ubivox.com",
    path: "/xmlrpc/",
    basic_auth: {
        user: "username",
        pass: "password"
    }
});

// Set the data field Name for user@example.com
client.methodCall(
    "ubivox.set_subscriber_data", 
    ["user@example.com", {
        Name: "John Doe"
    }],
    function (error, value) {
        if (error) throw error;
    }
);

Unsubscribing¶

var xmlrpc = require("xmlrpc");

var client = xmlrpc.createSecureClient({ 
    host: "company.clients.ubivox.com",
    path: "/xmlrpc/",
    basic_auth: {
        user: "username",
        pass: "password"
    }
});

// Cancel a subscription to list ID 42 for user@example.com
client.methodCall(
    "ubivox.cancel_subscription", 
    ["user@example.com", 42],
    function (error, value) {
        if (error) throw error;
    }
);

// Cancel a subscription to list ID 42 and 60 for user@example.com
client.methodCall(
    "ubivox.cancel_subscription", 
    ["user@example.com", 42, 60],
    function (error, value) {
        if (error) throw error;
    }
);

Create and send a delivery¶

var xmlrpc = require("xmlrpc");
var moment = require("moment");

var client = xmlrpc.createSecureClient({ 
    host: "company.clients.ubivox.com",
    path: "/xmlrpc/",
    basic_auth: {
        user: "username",
        pass: "password"
    }
});

// Create a new delivery on list ID 42
client.methodCall(

    "ubivox.create_delivery", 
    ["My first newsletter", "HTML body", "Text body", 42],

    function (error, value) {

        if (error) throw error;

        var delivery_id = value;

        // Schedule the delivery for delivery ASAP
        var now = moment().format("YYYY-MM-DD HH:mm:ss");

        client.methodCall(
            "ubivox.send_delivery", 
            [delivery_id, now],
            function (error, value) {
                if (error) throw error;
            }
        );

    }
);

Error/Exception handling¶

var xmlrpc = require("xmlrpc");

var client = xmlrpc.createSecureClient({ 
    host: "company.clients.ubivox.com",
    path: "/xmlrpc/",
    basic_auth: {
        user: "username",
        pass: "password"
    }
});

// Using opt-in to list ID 42 for user@example.com
client.methodCall(
    "ubivox.create_subscription", 
    ["user@example.com", 42, true], 
    function (error, value) {

        if (error) {

            if (error.faultCode == 1003) {
                console.log("You are already subscribed");
            } else {
                console.log(error.faultString);
            }

        } else {

            console.log("You are now subscribed");

        }

    }
);

Examples¶

Python Examples¶

Creating a new subscription¶

Updating subscriber data¶

Unsubscribing¶

Create and send a delivery¶

Error/Exception handling¶

PHP Examples¶

Creating a new subscription¶

Updating subscriber data¶

Unsubscribing¶

Create and send a delivery¶

Error/Exception handling¶

Node.js Examples¶

Creating a new subscription¶

Updating subscriber data¶

Unsubscribing¶

Create and send a delivery¶

Error/Exception handling¶

Table Of Contents

Previous topic

Next topic