Skip to content
The DNSimple API client for Go.
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
dnsimple Fix function comments based on best practices from Effective Go (#80) Mar 18, 2019
fixtures.http Update fixtures for `renewWhoisPrivacy` Feb 25, 2019
.travis.yml Update Mar 30, 2018
LICENSE.txt Remove references to NewOauthTokenCredentials Dec 1, 2018
go.mod Add go.mod to identify as a module Nov 16, 2018

DNSimple Go Client

A Go client for the DNSimple API v2.

Build Status GoDoc


$ go get


This library is a Go client you can use to interact with the DNSimple API v2. Here are some examples.

package main

import (


func main() {
    oauthToken := "xxxxxxx"
    ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: oauthToken})
    tc := oauth2.NewClient(context.Background(), ts)

    // new client
    client := dnsimple.NewClient(tc)

    // get the current authenticated account (if you don't know who you are)
    whoamiResponse, err := client.Identity.Whoami()
    if err != nil {
        fmt.Printf("Whoami() returned error: %v\n", err)


    // either assign the account ID or fetch it from the response
    // if you are authenticated with an account token
    accountID := strconv.Itoa(whoamiResponse.Data.Account.ID)

    // get the list of domains
    domainsResponse, err := client.Domains.ListDomains(accountID, nil)
    if err != nil {
        fmt.Printf("Domains.ListDomains() returned error: %v\n", err)

    // iterate over all the domains in the
    // paginated response.
    for _, domain := range domainsResponse.Data {

    // List methods support a variety of options to paginate, sort and filter records.
    // Here's a few example:

    // get the list of domains filtered by name and sorted by expiration
    client.Domains.ListDomains(accountID, &dnsimple.DomainListOptions{NameLike: "com", Sort: "expiration:DESC"})

For more complete documentation, see godoc.


When creating a new client you are required to provide an http.Client to use for authenticating the requests. Currently supported authentication mechanisms are OAuth and HTTP Digest.

For OAuth we suggest to use the client provided by the package:

ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: "XXX"})
tc := oauth2.NewClient(context.Background(), ts)

// new client
client := dnsimple.NewClient(tc)

For HTTP Digest you can use the client provided by this package:

tp := dnsimple.BasicAuthTransport{
    Username: "XXX",
    Password: "XXX",

client := dnsimple.NewClient(tp.Client())

For any other custom need you can define your own http.RoundTripper implementation and pass a client that authenticated with the custom round tripper.

Sandbox Environment

We highly recommend testing against our sandbox environment before using our production environment. This will allow you to avoid real purchases, live charges on your credit card, and reduce the chance of your running up against rate limits.

The client supports both the production and sandbox environment. To switch to sandbox pass the sandbox API host using the base_url option when you construct the client:

client := dnsimple.NewClient(tc)
client.BaseURL = ""

You will need to ensure that you are using an access token created in the sandbox environment. Production tokens will not work in the sandbox environment.

Setting a custom User-Agent header

You customize the User-Agent header for the calls made to the DNSimple API:

client := dnsimple.NewClient(tc)
client.UserAgent = "my-app"

The value you provide will be appended to the default User-Agent the client uses. For example, if you use my-app, the final header value will be dnsimple-go/0.14.0 my-app (note that it will vary depending on the client version).


For instructions about contributing and testing, visit the CONTRIBUTING file.


Copyright (c) 2014-2018 Aetrion LLC. This is Free Software distributed under the MIT license.

You can’t perform that action at this time.