Notification API¶

Introduction¶

The Gandi Notification API provides a set of remote requests to manage your notifications.

Connect to the API server¶

The Gandi Notification API is provided through a set of XML-RPC calls:

python
php
nodejs
perl
ruby
C

>>> import xmlrpc.client
>>> api = xmlrpc.client.ServerProxy('https://rpc.gandi.net/xmlrpc/')
>>>
>>> apikey = 'my 24-character API key'
>>>
>>> # Now you can call API methods.
>>> # You must authenticate yourself by passing
>>> # the API key as the first method's argument
>>> version = api.version.info(apikey)

Note

In Python, use the xmlrpcclient module from the standard library.

<?php
// Library installed from PEAR
require_once 'XML/RPC2/Client.php';

// The first step is to connect to the API
$version_api = XML_RPC2_Client::create(
    'https://rpc.gandi.net/xmlrpc/',
    array( 'prefix' => 'version.', 'sslverify' => True )
);

// Warning !
// PEAR::XML_RPC2 checks the SSL certificate with Curl
// Curl has its own CA bundle so you may :
// * disable the 'sslverify' option: leads to security issue
// * enable the 'sslverify' option (default) and add the Gandi
// SSL certificate to the Curl bundle: best choice for security
// See: https://curl.haxx.se/docs/sslcerts.html

$apikey = 'my 24-character API key';

// Now you can call API method
// You must authenticate yourself by passing the API key
// as the first method's argument
$result = $version_api->info($apikey);

// Warning !
// PEAR::XML_RPC2 has known bugs on methods calls
// See https://pear.php.net/bugs/bug.php?id=13963
// You may use this call instead of the above one :
// $result = $version_api->__call("info", $apikey);

// dump the result
print_r($result);
?>

Note

In PHP 5, use the XML_RPC2 package from pear.

XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have to instanciante a client by namespace.

> var xmlrpc = require('xmlrpc')
> var api = xmlrpc.createSecureClient({
...  host: 'rpc.gandi.net',
...  port: 443,
...  path: '/xmlrpc/'
... })
>
> var apikey = 'my 24-character API key'
>
> // Now you can call API methods.
> // You must authenticate yourself by passing the API key
> // as the first method's argument
> api.methodCall('version.info', [apikey], function (error, value) {
...  console.dir(value)
... })

Note

With NodeJS, use the npm xmlrpc package.

use XML::RPC;

my $api = XML::RPC->new('https://rpc.gandi.net/xmlrpc/');

my $apikey = 'my 24-character API key';

# Now you can call API methods.
# You must authenticate yourself by passing the API key
# as the first method's argument
my $version = $api->call( 'version.info', $apikey );

Note

With perl, use the cpan xml::rpc package.

require 'xmlrpc/client'

server = XMLRPC::Client.new2('https://rpc.gandi.net/xmlrpc/')

apikey = 'my 24-character API key'

# Now you can call API methods.
# You must authenticate yourself by passing the API key
# as the first method's argument
version = server.call("version.info", apikey)

Note

With ruby, use the xmlrpc/client module from the standard library. Ruby does not support gzip by default, the ZlibParserDecorator is used to enabled with Ruby >1.9.

For older ruby version, neither set the http_header_extra nor the parser.

Note

To avoid RuntimeError with ruby >= 1.9, add:

XMLRPC::Config.module_eval {
    remove_const(:ENABLE_NIL_PARSER)
    const_set(:ENABLE_NIL_PARSER, true)
}

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <xmlrpc.h>
#include <xmlrpc_client.h>

#define CLIENT_NAME             "Documentation Client"
#define CLIENT_VERSION          "0.1"
#define CLIENT_USERAGENT        CLIENT_NAME "/" CLIENT_VERSION

#define SERVER_URL              "https://rpc.gandi.net/xmlrpc/"

int     client_connect(xmlrpc_env *);
void    client_check_fault(xmlrpc_env *);

int
main(int argc, char **argv)
{
        xmlrpc_env      env;
        xmlrpc_value    *apikey, *rv;

        client_connect(&env);

        apikey = xmlrpc_build_value(&env, "(s)", "my 24-character API key");
        rv = xmlrpc_client_call_params(&env, SERVER_URL, "version.info", apikey);
        client_check_fault(&env);

        xmlrpc_DECREF(rv);
        xmlrpc_DECREF(apikey);

        xmlrpc_env_clean(&env);
        xmlrpc_client_cleanup();

        return (0);
}

int
client_connect(xmlrpc_env *env)
{
        struct xmlrpc_clientparms clientp;
        struct xmlrpc_curl_xportparms curlp;

        curlp.network_interface = NULL;         /* use curl's default */
        curlp.ssl_verifypeer = 1;               /* Gandi API CA must be present */
        curlp.ssl_verifyhost = 2;
        curlp.user_agent = CLIENT_USERAGENT;    /* XML-RPC requirement */

        clientp.transport = "curl";
        clientp.transportparmsP = &curlp;
        clientp.transportparm_size = XMLRPC_CXPSIZE(user_agent);

        xmlrpc_env_init(env);
        xmlrpc_client_init2(env, XMLRPC_CLIENT_NO_FLAGS, CLIENT_NAME,
            CLIENT_VERSION, &clientp, XMLRPC_CPSIZE(transportparm_size));
        client_check_fault(env);

        return (1);
}

void
client_check_fault(xmlrpc_env *env)
{
        if (env->fault_occurred) {
                fprintf(stderr, "XML-RPC Fault: %s (%d)\n", env->fault_string,
                    env->fault_code);
                exit(1);
        }
}

Note

With C, use the xmlrpc-c library.

Note

the Notification API does not use the standard HTTP authentication scheme. It uses a custom authentication mechanism based on the API key.

Notification Management¶

Explaining notifications¶

domain.delete_foa: This notification is sent when the FOA confirmation for a domain deletion is sent to the domain owner.
domain.delete_foa_reselle: This notification is sent when the FOA confirmation for a domain deletion is sent to the domain owner on behalf of the reseller.
domain.delete_done_reseller: This notification is sent to the reseller when a domain has been deleted from the registry.
domain.transfer_out: This notification is sent when GANDI has been notified of a registrar transfer request, to alert the domain owner that it will be effective in 5 days.
domain.transfer_out_reselle: This notification is sent when GANDI has been notified of a registrar transfer request, to alert the reseller that he will be unable to manage the domain from the GANDI account in 5 days.
domain.transfer_out_done_reselle: This notification is sent when the domain has been transfered to another registrar and is no longer managed by GANDI.
domain.reachability_reseller: This notification is sent to the reseller when a contact reachability status changes: pending, done, failed.
domain.contact_validation: This notification is sent to the domain owner or the reseller, when a contact validation data is required, as it is done for .uk.
iaas.create: This notification is sent after every server creation.
iaas.update: This notification is sent following each server modification.
paas.create: This notification is sent when a Simple Hosting instance is created.
site.create: This notification is sent when a website is created.
ssl.backend: These notifications will be sent during various certificate purchasing processes.
domain.creation: Not yet available.
domain.renewal_reminder: Not yet available.
domain.grouped_renewal_reminder: Not yet available.
domain.renewal: Not yet available.
domain.automatic_renewal: Not yet available.
domain.transfer: Not yet available.
domain.restore: Not yet available.
domain.change_owner: Not yet available.
domain.update: Not yet available.
contact.update: Not yet available.
contact.password_update: Not yet available.
billing.new_invoice: Not yet available.
billing.credit_alert: Not yet available.
iaas.credit_alert: Not yet available.
paas.renewal_reminder: Not yet available.
paas.renewal: Not yet available.
site.renewal_reminder: Not yet available.
site.renewal: Not yet available.
ssl.renewal_reminder: Not yet available.

List availables notifications¶

To list the available notifications and their associated channels, just call the method notification.list():

>>> api.notification.list(apikey)
[{'active': True,
  'channels': [{'name': 'irc', 'status': 'inactive'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'inactive'}],
  'name': 'billing.credit_alert'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'}],
  'name': 'billing.new_invoice'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'contact.password_update'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'contact.update'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.automatic_renewal'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.change_owner'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.creation'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'}],
  'name': 'domain.delete_done_reseller'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'}],
  'name': 'domain.delete_foa'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'}],
  'name': 'domain.delete_foa_reselle'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.grouped_renewal_reminder'},
 {'active': True,
  'channels': [{'name': 'sns', 'status': 'active'}],
  'name': 'domain.reachability_reseller'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.renewal'},
 {'active': False,
  'channels': [{'name': 'irc', 'status': 'inactive'},
               {'name': 'smtp', 'status': 'inactive'},
               {'name': 'xmpp', 'status': 'inactive'}],
  'name': 'domain.renewal_reminder'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.restore'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.transfer'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'inactive'}],
  'name': 'domain.transfer_out'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'inactive'}],
  'name': 'domain.transfer_out_reselle'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.update'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'iaas.create'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'inactive'},
               {'name': 'sms', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'inactive'}],
  'name': 'iaas.credit_alert'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'inactive'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'iaas.update'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'paas.create'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'paas.renewal'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'paas.renewal_reminder'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'site.create'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'site.renewal'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'site.renewal_reminder'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'}],
  'name': 'ssl.backend'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'ssl.renewal_reminder'}]

Count availables notifications¶

To count how many notifications are avalaible at a given time, just call the notification.count() method:

>>> api.notification.count(apikey)
23

Test your notification subscriptions¶

If you want to test your notifications setup, you may execute the notification.test() method:

>>> api.notification.test(apikey, 'paas.create')
True

You should then receive on all subscribed addresses a message saying

Hello, this is a Gandi Notification test message for notification paas.create

Notification content samples¶

Here are some samples of notifications content for SNS channels.

domain.reachability_reseller: This notification is sent to the reseller when a contact reachability status changes: pending, done, failed.

{'status': 'pending',
 'handle': 'XXXX1234-GANDI',
 'platform': 'production',
 'date_end': '2016-01-01 08:36:32',
 'date': '2015-12-17 08:39:06',
 'source_notification': 'domain.reachability_reseller',
 'domains': "['pizzza.xyz']",
 'date_created': '2015-12-17 08:35:20'}

{'status': 'done',
 'handle': 'XXXX1234-GANDI',
 'platform': 'production',
 'date_end': '2015-12-17 08:37:20',
 'date': '2015-12-17 10:48:27',
 'source_notification': 'domain.reachability_reseller',
 'domains': u"['pizzza.xyz']",
 'date_created': '2015-12-17 08:35:20'}

{'status': 'failed',
 'handle': 'XXXX1234-GANDI',
 'platform': 'production',
 'date_end': '2015-12-17 10:55:59',
 'date': '2015-12-17 10:59:06',
 'source_notification': 'domain.reachability_reseller',
 'domains': u"['pizzza.xyz']",
 'date_created': '2015-12-17 10:53:59'}

domain.transfer_out_done_reselle: This notification is sent when the domain has been transfered to another registrar and is no longer managed by GANDI.

{'platform': 'production',
 'domain': 'pizzza.xyz',
 'source_notification': 'domain.transfer_out_done_reselle'}

Gandi

Table of Contents

Previous topic

Next topic

Notification API¶

Introduction¶

Connect to the API server¶

Notification Management¶

Explaining notifications¶

List availables notifications¶

Count availables notifications¶

Test your notification subscriptions¶

Notification content samples¶

Gandi

Quick search

Table of Contents

Previous topic

Next topic

Notification API¶

Introduction¶

Connect to the API server¶

Notification Management¶

Explaining notifications¶

List availables notifications¶

Count availables notifications¶

Test your notification subscriptions¶

Notification content samples¶