Python client for DNSimple domain registration and DNS hosting
Python Makefile
Latest commit ee0e89b Sep 5, 2016 @onlyhavecans committed on GitHub Merge pull request #18 from mdippery/master
Remove unnecessary print statement


Python DNSimple


This is a client for the DNSimple REST API. It currently allows you to fetch existing domain info, as well as register new domains and manage domain records.

dnsimple-python works for both python 2 & 3.

Getting started

You'll need the json module that is included with python version 2.6 and later, or the simplejson module if you are using an earlier version.

dnsimple-python also depends on the requests library.

Import the module:

from dnsimple import DNSimple

You can provide your DNSimple credentials in one of two ways:

  1. Provide username/password or email/api_token credentials programmatically:

    # Use username/password authentication: HTTP Basic
    dns = DNSimple(username=YOUR_USERNAME, password=YOUR_PASSWORD)
    # Use email/api_token credentials
    dns = DNSimple(email=YOUR_EMAIL_ADDRESS, api_token=YOUR_API_TOKEN)
  2. Store you username/password or email/api_token credentials in a file called .dnsimple in the current directory with the following data:

    password: yourpassword


    api_token: yourapitoken

    Or (assuming $DNSIMPLE_EMAIL and $DNSIMPLE_TOKEN are environment variables):

    email: %(DNSIMPLE_EMAIL)s
    api_token: %(DNSIMPLE_TOKEN)s

    You then need not provide any credentials when constructing DNSimple:

    dns = DNSimple()

Domain Operations

Check out your existing domains:

Just run:

domains =

Results appear as a Python dict:

{'domain': {'created_at': '2010-10-14T09:45:32Z',
            'expires_at': '10/14/2011 5:45:00 AM',
            'id': 999,
            'last_enom_order_id': None,
            'name': '',
            'name_server_status': 'active',
            'registrant_id': 99,
            'registration_status': 'registered',
            'updated_at': '2010-10-14T10:00:14Z',
            'user_id': 99}},
{'domain': {'created_at': '2010-10-15T16:02:34Z',
            'expires_at': '10/15/2011 12:02:00 PM',
            'id': 999,
            'last_enom_order_id': None,
            'name': '',
            'name_server_status': 'active',
            'registrant_id': 99,
            'registration_status': 'registered',
            'updated_at': '2010-10-15T16:30:16Z',
            'user_id': 99}}]

Get details for a specific domain


Results are the same as domains() above, but only show the domain specified.

Check whether a domain is available


# Hmm, looks like I'm too late to get that one...
{u'currency': u'USD',
 u'currency_symbol': u'$',
 u'minimum_number_of_years': 1,
 u'name': u'',
 u'price': u'14.00',
 u'status': u'unavailable'}

Register a new domain


This will register '', automatically picking the registrant_id from your first domain. To specify a particularly registrant_id, just run:

dns.register('', 99)

Responses will be in a dictionary describing the newly created domain, same as the domain() call above.

Delete a domain

Careful with this one!


Record operations

All operations on domain records are now supported:

  • List records: records(id_or_domainname)
  • Get record details: record(id_or_domainname, record_id)
  • Add record: add_record(id_or_domainname, data)
  • Update record: update_record(id_or_domainname, record_id, data)
  • Delete record: delete_record(id_or_domainname, record_id)

Running Tests

Before running tests, you'll need to ensure your environment is set up correctly:

  1. If you don't already have a DNSimple sandbox account, create one and make sure to have your email address, password, and API token handy.
  2. Ensure you have the virtualenv package installed (pip install virtualenv --upgrade) since tests are run from this isolated environment
  3. Copy the file tests/.env.example to tests/.env and supply your sandbox credentials
  4. From the project root, run make test -- this will set up your local environment with virutalenv, install all necessary dependencies, and run all the tests.


Licensed under the MIT license