NAV
json xml

Introduction

Welcome to the API documentation of http.net.

How to navigate the API documentation:

The left column functions as an overview of our services. You can use it as an intuitive navigation. Click on a topic and find specific information for that service, object, or method. The middle column provides you with the information you are looking for. The column on the right shows you examples in JSON as well as in XML format.

What the API can do for you:

Our API allows you to manage your resources and those of your subaccounts’ in an easy way, using HTTP requests. Various document formats like JSON or XML are supported. Each resource type is managed in a service (e.g.: domain, DNS, SSL, etc.) with its own endpoint that provides default methods like listings as well as specific methods for the service.

One of the core principles of our platform system is to offer the same access level to every user. For example, the platform ‘web control panel’ uses the JSON-API, so everything you do with the panel can also be done using the API. This concept allows you to program and script very complex applications and to tailor them to your needs.

First, the API documentation gives you a general overview of the design and technology that has been implemented, followed by reference information about specific services.

Requests and Authentication

In order to communicate with the API, you simply have to use the right endpoint and a tool that is able to understand HTTP. Every request has to contain an appropriate Accept and Content-Type header.

The supported HTTP methods are POST and OPTIONS.

To access a specific service, you have to use the right endpoint. They are built in the following manner:

https://partner.http.net/api/{service}/{api-version}/{format}/{method}

So, an exemplary URL could look like this:

https://partner.http.net/api/account/v1/json/subaccountCreate.

This structure is valid for all document formats except for SOAP. In that case, the {method} parameter is embedded within the request document. This is what an equivalent SOAP request URL looks like:

https://partner.http.net/api/account/v1/soap/

Our goal is to keep code snippets clean and simple. The majority of developers using SOAP also use a generator for the WSDL file anyway. Please take a look at the JSON or XML examples, because we will not provide examples for SOAP.

Authentication

{
    "authToken": "$$YOUR API KEY$$"
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
</request>

Every request you send must contain the authToken parameter which has to be set to your API key. You can generate API keys in the web control panel.

Remember that API keys might have their own set of rights. This allows you to give your API key exactly the rights that you need for your application.

Request Delegation

{
    "authToken": "$$YOUR API KEY$$",
    "ownerAccountId": "$$ID OF YOUR SUBACCOUNT$$"
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <ownerAccountId>$$ID OF YOUR SUBACCOUNT$$</ownerAccountId>
</request>

Since subaccount handling is an important feature of the platform system, you can execute every request in the name of your account or any of your subaccounts. To execute a request as a subaccount, you need to add an ownerAccountId parameter containing the ID of the desired subaccount.

Thus the access and right validation will be performed as if the subaccount itself made the request. If your subaccount does not have the right or access to perform the operation, the request will fail - even if your main account or you have this right or access.

Responses

Sample single object response
{
    "responses": [
        "text list element 1",
        "text list element 2"
    ],
    "status": "success",
    ...
}
<response>
    <responses>
        <item>text list element 1</item>
        <item>text list element 2</item>
    </responses>
    <status>success</status>
    ...
</response>

Every request will return a response body in the same format of you request. A list of elements contains a responses object and a single element contains a response object.

Sample list response
{
    "authToken": "$$YOUR API KEY$$",
    "ownerAccountId": "$$ID OF YOUR SUBACCOUNT$$"
}
<request>
    <authToken>$$YOUR API KEY$$</authToken>
    <ownerAccountId>$$ID OF YOUR SUBACCOUNT$$</ownerAccountId>
</request>

If you receive a response body, it will contain a status element that specifies the result in general. The status may have one of the three following values:

Status Description
success The request was successful and processed in a synchronous manner. This usually applies to listings or requests which do not need to access a third party interface.
pending The request was successful but could not be processed in a synchronous manner. This applies to requests which need to access a third party interface in order to be completed, or to requests which may take a long time to complete. You will be informed of the result of these requests via poll messages.
error This status will occur, if there are any problems while processing your request. This could be a data or access violation or an error in a third party interface.

Metadata Object

{
    "metadata": {
       "clientTransactionId": "$$CLIENT STRING ID$$",
       "serverTransactionId": "UNIQUE SERVER TRANSACTION ID"
   },
    ...
}
<response>
    <metadata>
      <clientTransactionId>$$CLIENT STRING ID$$</clientTransactionId>
      <serverTransactionId>A UNIQUE SERVER TRANSACTION ID</serverTransactionId>
   </metadata>
    ...
</response>

Every developer faces the problem of matching responses or poll messages to requests. To simplify this process for you as much as possible, we provide a metadata object. This object contains a clientTransactionId element and a serverTransactionId element which will help you to keep track of your communication with the API.

Every request may contain an optional clientTransactionId parameter. You can fill this element with any string up to a length of 127 characters. The response and polls associated with your request will contain the same string. The serverTransactionId element is filled by the server and will be present in the response. This ID is unique throughout the whole system. It will also be present in every poll message you receive that is associated with that request.

HTTP Status Codes

While most errors will be communicated via API error codes, some low level issues may cause transport level errors. You should handle the following error codes with an application:

Code Meaning
200 OK
400 The HTTP request was malformed
404 Method, format, or entry point not found
405 Method not allowed
500 Internal server error
502 Server temporarily not available
503 Server temporarily not available due to maintenance
504 Backend timeout

Warnings and Errors

Request contactCreate
{
    "authToken": "$$YOUR API KEY$$",
    "contact": {
        "type": "asd",
        "phone": "+49",
        ...
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contact>
  <type>asd</type>
  <phone>+49</phone>
   ...
 </contact>
</request>
Response
{
    "status": "error",
    "errors": [
        {
            "code": 32002,
            "contextObject": "",
            "contextPath": "/contact/type",
            "details": [],
            "text": "Handle type is invalid",
            "value": "asd"
        },
        {
            "code": 32022,
            "contextObject": "",
            "contextPath": "/contact/phone",
            "details": [],
            "text": "Format of the phone number is invalid. The E.123 international notation is required",
            "value": "+49"
        }
    ],
    ...
}
<response>
 <status>error</status>
 <errors>
  <item>
   <code>32002</code>
   <contextObject></contextObject>
   <contextPath>/contact/type</contextPath>
   <details/>
   <text>Handle type is invalid</text>
   <value>asd</value>
  </item>
  <item>
   <code>32022</code>
   <contextObject></contextObject>
   <contextPath>/contact/phone</contextPath>
   <details/>
   <text>Format of the phone number is invalid. The E.123 international notation is required</text>
   <value>+49</value>
  </item>
 </errors>
 ...
</response>

If an error occurs, you will receive detailed information. To speed up the development process and to help prevent a try and error approach, the API collects all errors and warnings related to your request. The response will contain a list of error objects.

Your request may also contain an error that the API will automatically fix. In that case, the response will contain a list of warnings as well. The warnings tell you what was wrong and what the API did to fix the problem (for example a TTL value was too small, so it was raised to the minimum value).

The error object contains a code element which masks the specific error code. The code consists of multiple digits: The last four digits specify the occured error. The digits further up front specify the respective service.

The text contains a human-readable error description. This text can be used to give feedback to users of your application.

If you modify an existing object, the contextObject will be set to its ID. In case of a create request, the field will be empty. In case of a data violation error, the value property shows you the content of the member that caused the error.

details is a list of key/value objects which provide additional information about the specific error. This might help you with debugging or presenting a more detailed error to your user.

The contextPath is a value which points to the element that caused the error. This will help you to easily identify this element in your request document. For JSON requests we use JSON-Pointers (RFC 6901), for XML and SOAP we use XPath (RFC 5261).

Filtering and Sorting

{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "subFilterConnective": "OR",
        "subFilter": [
            {
                "field": "domainNameAce",
                "value": "$$DOMAIN NAME 1$$"
            },
            {
                "field": "domainNameAce",
                "value": "$$DOMAIN NAME 2$$",
                "relation": "unequal"
            }
        ]
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "domainNameAce",
        "order": "ASC"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <subFilterConnective>OR</subFilterConnective>
  <subFilter>
   <item>
    <field>domainNameAce</field>
    <value>$$DOMAIN NAME 1$$</value>
   </item>
   <item>
    <field>domainNameAce</field>
    <value>$$DOMAIN NAME 2$$</value>
    <relation>unequal</relation>
   </item>
  </subFilter>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>domainNameAce</field>
  <order>ASC</order>
 </sort>
</request>

Each service offers listing methods for the resources it manages. These methods are identical throughout the whole system. Different are the fields you can search in or sort by. The signature of each listing method accepts the following parameters:

Parameter Type Required Description
filter Filter or Chain opt Filter object for the request
limit number opt Maximal number of records that should be returned (Defaults to 25)
page number opt Translates to an offset in the record list.
sort SortOptions opt Fields the result is sorted by

Filter Object

{
    "field": "domainName",
    "value": "example.com"
}
<filter>
 <field>domainName</field>
 <value>example.com</value>
</filter>
Property Type Required Description
field string req Field name
value string req Contains the search string
relation string opt Determins the relation between field and value. Defaults to ‘equal’

In its simplest form, the filter parameter takes a field and a value parameter. The result will match to this condition. The field element refers to the field you want to filter. value is the argument for that field. By default, the value is a case-insensitive exact match. An asterisk (*) can be used to match an arbitrary number of characters (including zero characters).

The field element is restricted to a list of field names which vary from listing to listing. You can find lists of available and valid fields throughout the API. Please refer to specific documentation sections for the respective finding methods. Field names are case insensitive.

The relation element specifies the comparison performed on field and the specific value. It is an optional element and defaults to 'equal’ if not set. Please see the table below for further details and explainations.

Available relations

Relation Description
equal field must match value exactly
unequal field must not be the same as value
greater field must be greater than value. This might apply to e.g. an integer value, a date or a date time
less field must be less than value. This might apply to e.g. an integer value, a date or a date time
greaterEqual field must be greater than or equal to value. This might apply to e.g. an integer value, a date or a date time
lessEqual field must be less than or equal to value. This might apply to e.g. an integer value, a date or a date time
{
    "subFilterConnective": "OR",
    "subFilter": [
        {"field": "domainName", "value": "*.de"},
        {"field": "domainName", "value": "*.com"}
    ]
}
<filter>
 <subFilterConnective>OR</subFilterConnective>
 <subFilter>
  <item>
   <field>domainName</field>
   <value>*.de</value>
  </item>
  <item>
   <field>domainName</field>
   <value>*.com</value>
  </item>
 </subFilter>
</filter>

Complex queries can be created by chaining condition objects with a chain object. Chain objects can contain further chain objects.

Chain Object

Property Type Required Description
subFilter list<Filter or Chain> req Contains other filter objects
subFilterConnective string req AND or OR

If you are using the SOAP API you have to use the Filter SOAP type for both Filter and Chain objects.

Response

The response will contain an object wrapping the results and some meta information for pagination.

{
    "data": [
        ...
    ],
    "limit": 10,
    "page": 1,
    "totalEntries": 50,
    "totalPages": 5,
    "type": "FindDomainsResult"
}
<response>
 <data>
  ...
 </data>
 <limit>10</limit>
 <page>1</page>
 <totalEntries>50</totalEntries>
 <totalPages>5</totalpages>
 <type>FindDomainsResult</type>
</response>
Property Type Direction Description
page int out-only Page number as requested
limit int out-only Limit as requested
totalEntries int out-only Total number of results
totalPages int out-only Total number of result pages
data list<…> out-only Found objects

Domains

The domain part of the API allows to create and maintain domains in a wide variety of domain name registries.

Each domain requires contact information of the owner as well as other individuals and organizations involved in maintaining the domain.

Allocation Description
owner Legal owner of domain name
admin Administrative contact
tech Technical contact
zone Contact for issues regarding the DNS servers or DNS setup of the domain

If a registry has a separate billing contact, the admin contact will be used as billing contact in registry operations.

Each domain requires two or more name servers. They need to serve authoritative answers regarding host names in the DNS zone corresponding to the domain.

The Contact Object

{
    "accountId": "15010100000001",
    "id": "15010100000010",
    "handle": "JS15",
    "type": "person",
    "name": "John Smith",
    "organization": "",
    "street": [
        "Happy ave. 42"
    ],
    "postalCode": "12345",
    "city": "Where ever",
    "state": "",
    "country": "de",
    "emailAddress": "john@example.com",
    "phoneNumber": "+49 1234 567890",
    "faxNumber": "",
    "sipUri": "",
    "hidden": false,
    "usableBySubAccount": false,
    "addDate": "2015-01-01T00:00:00",
    "lastChangeDate": "2015-01-01T00:00:00"
}
<id>15010100000000</id>
<accountId>15010100000000</accountId>
<handle>JS15</handle>
<type>person</type>
<name>John Smith</name>
<organization></organization>
<street>
    <item>Happy ave. 42</item>
</street>
<postalCode>12345</postalCode>
<city>Where ever</city>
<state></state>
<country>de</country>
<emailAddress>john@example.com</emailAddress>
<phoneNumber>+49 1234 567890</phoneNumber>
<faxNumber></faxNumber>
<sipUri></sipUri>
<hidden>false</hidden>
<usableBySubAccount>false</usableBySubAccount>
<addDate>2015-01-01T00:00:00</addDate>
<lastChangeDate>2015-01-01T00:00:00</lastChangeDate>

The contact object is used for managing domains. It can have one of three types:

Contact Object

Property Type Required / Direction Description
accountId string out-only ID of contact managing account. Field never used in requests.
id string see description Contact ID. Ignored in contact create requests. Either id or handle is required in all other requests.
handle string see description Contact handle. Ignored in contact create requests. Either id or handle is required in all other requests.
type string req Valid types are person, org, and role
name string req Full contact name. For organizations this is the name of a contact in the organization.
organization string see description Is a required field for org handles. Name of the organization
Example: Beispiel Ltd.
street list<string> req List of address entries. Contains up to three entries.
postalCode string opt Postal code (address)
city string req City (address)
state string opt State (address)
country string req Country code in ISO 3166-1 alpha-2 (see iso.org or Wikipedia). Will always be returned in lower case.
Example: de
emailAddress string req Must be a valid email address
phoneNumber string req The phone number consists of country code, area code and the local number. These three parts are separated by spaces. Additional spaces are not allowed.
example: +49 123 4567890.
faxNumber string opt Fax number (same rules apply as for the phone number)
Example: +49 123 4567899
sipUri string opt SIP URI
hidden bool opt Can be used to mark unwanted contacts that are still in use. If a hidden contact is used as domain handle, the API will warn you.
usableBySubAccount bool opt Allows direct subaccounts to use this contact
addDate datetime out-only Date and time of contact creation
lastChangeDate datetime out-only Date and time the contact was last modified

Listing Contacts

POST https://partner.http.net/api/domain/v1/jsonxml/contactsFind
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "filter": {
        "field": "ContactName",
        "value": "*Smith*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "ContactName",
        "order": "asc"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <clientTransactionId></clientTransactionId>
 <filter>
  <field>ContactName</field>
  <value>*Smith*</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>ContactName</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // contact objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindContactsResult"
    },
    ...
}
<response>
 <response>
  <data/>
     // contact objects
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindContactsResult</type>
 </response>
</response>
RequestcontactsFind
Urlhttps://partner.http.net/api/domain/v1/jsonxml/contactsFind
Processingsynchronous
ResponseFindContactsResult

Listing contacts uses the generic filtering and sorting API with the method contactsFind. The response will contain a list of Contact objects.

The following fields are available for filtering and sorting:

Field Description
AccountId Managing account ID
ContactId ID of contact
ContactHandle Handle of contact
ContactType Type of contact (cf. Contact object)
ContactName Name of contact
ContactOrganization Organization of contact
ContactStreet All street entries (contact address)
ContactPostalCode Postal code (contact address)
ContactCity City (contact address)
ContactState State (contact address)
ContactCountry Country of address in ISO 3166-1 alpha-2 (cf. Contact objects)
ContactEmailAddress Email address of contact
ContactPhoneNumber Phone number of contact (format, cf. Contact objects)
ContactFaxNumber Fax number of the contact (format, cf. Contact objects)
ContactSipUri SIP URI of contact
ContactUsableBySubAccount Contact is usable by subaccounts
ContactHidden Contact is hidden
UsableForDomainInAccount Must be an account ID. If set, the listing will only return contacts that are usable for domain operations for that specific account.
ContactAddDate Date and time the contact was created
ContactLastChangeDate Date and time the contact was last modified

Retrieving Specific Contacts

POST https://partner.http.net/api/domain/v1/jsonxml/contactInfo
{
    "authToken": "$$YOUR API KEY$$",
    "contactId": "15010100000010"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contactId>15010100000010</contactId>
</request>
Response
{
    ...
    "response": {
        // contact object
    },
    ...
}
<response>
 ...
 <response>
     // contact object
 </response>
 ...
</response>
RequestcontactInfo
Urlhttps://partner.http.net/api/domain/v1/jsonxml/contactInfo
Processingsynchronous
ResponseContact object
Parameter Type Required Description
contactId string req ID of contact

In order to retrieve a specific contact, you can either use the contactsFind method and use the ContactId filter or you can use the contactInfo method which uses a contact ID as input and returns the contact object, if it exists.

Creating New Contacts

POST https://partner.http.net/api/domain/v1/jsonxml/contactCreate
{
    "authToken": "$$YOUR API KEY$$",
    "contact": {
        "type": "person",
        "name": "John Smith",
        "organization": "",
        "street": [
            "Happy ave. 42"
        ],
        "postalCode": "12345",
        "city": "Where ever",
        "country": "de",
        "emailAddress": "john@example.com",
        "phoneNumber": "+49 1234 567890"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contact>
  <type>person</type>
  <name>John Smith</name>
  <organization></organization>
  <street>
   <item>Happy ave. 42</item>
  </street>
  <postalCode>12345</postalCode>
  <city>Where ever</city>
  <country>de</country>
  <emailAddress>john@example.com</emailAddress>
  <phoneNumber>+49 1234 567890</phoneNumber>
 </contact>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "id": "15010100000010",
        "handle": "JS15",
        "addDate": "2015-01-01T00:00:00",
        "lastChangeDate": "2015-01-01T00:00:00",
        ...
    },
    ...
}
<response>
 <response>
  <id>15010100000010</id>
  <accountId>15010100000001</accountId>
  <handle>JS15</handle>
  <addDate>2015-01-01T00:00:00</addDate>
  <lastChangeDate>2015-01-01T00:00:00</lastChangeDate>
 </response>
</response>
RequestcontactCreate
Urlhttps://partner.http.net/api/domain/v1/jsonxml/contactCreate
Processingsynchronous
ResponseContact object
Parameter Type Required Description
contact Contact object req Complete contact object

This method is used to create a new contact in the system. The object must contain all required fields. id and handle fields can be filled, but will be ignored. The response will contain the newly created contact object.

Updating Contacts

POST https://partner.http.net/api/domain/v1/jsonxml/contactUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "contact": {
        "handle": "JS48", // or "id": "15010100000010"
        ...
        "emailAddress": "jane@example.com",
        ...
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <contact>
 <handle>JS48</handle> // or <id>15010100000010</id>
  ...
  <emailAddress>jane@example.com</emailAddress>
  ...
 </contact>
</request>
Response
{
    ...
    "response": {
        ...
        "emailAddress": "jane@example.com",
        "lastChangeDate": "2015-01-01T12:00:00",
        ...
    },
    ...
}
<response>
 ...
 <response>
  ...
  <emailAddress>jane@example.com</emailAddress>
  <lastChangeDate>2015-01-01T12:00:00</lastChangeDate>
  ...
 </response>
 ...
</response>
RequestcontactUpdate
Urlhttps://partner.http.net/api/domain/v1/jsonxml/contactUpdate
Processingasynchronous
ResponseContact object
Parameter Type Required Description
contact Contact object req Complete contact object
actingAs string opt see below

The contact to update can either be identified by id or by handle. All fields not marked ‘out-only’ are set to the values in the contact argument. Optional fields that are not specified in this request are reset to their default values.

The update is pushed to every registry the contact is connected to. This will result in seperate jobs for every registry.

Please note that type, name, and organization of a contact cannot be changed. Some registries do not allow changing phone numbers as well. In case the contact is used in a domain from these registries, the API will return a synchronous error.

The email of a contact that is linked to a domain in a generic extension (com, net, etc) may only be changed by an account that acts as an designated agent of both the new and the old contact.

By passing designatedAgent as the actingAs parameter you affirm that the current and the new contact have explicitly opted in to authorize you to approve a Change of Registrant on their behalf.

To check if an update is an owner change under ICANN rules (i.e. is material change and affects domains under icann rules) you can use the contactUpdateIsIcannOwnerChange api function.

RequestcontactUpdateIsIcannOwnerChange
Urlhttps://partner.http.net/api/domain/v1/jsonxml/contactUpdateIsIcannOwnerChange
Processingsynchronous
Responsebool
Parameter Type Required Description
contact Contact object req contact object to check

Deleting Contacts

Deleting contacts via API is not possible at the moment and might never be. Unused contacts will automatically be deleted after a while. In that case, an automatic poll message will inform you.

If you want to hide a contact, you can set the hidden parameter to true. Then, the contact will not be shown in the web control panel for registering new domains. Also, the contactsFind method will not return the contact any longer, if you use the filter UsableForDomainInAccount.

The Domain Object

{
    "id": "150101000000010",
    "accountId": "150101000000001",
    "name": "example.com",
    "nameUnicode": "example.com",
    "status": ["ok"],
    "transferLockEnabled": false,
    "authInfo": "1234,ABCD+xyz",
    "contacts": [
        {
            "contact": "150101000000021",
            "type": "owner"
        },
        {
            "contact": "150101000000020",
            "type": "admin"
        },
        {
            "contact": "150101000000022",
            "type": "tech"
        },
        {
            "contact": "150101000000023",
            "type": "zone"
        }
    ],
    "nameservers": [
        {
            "ips": [],
            "name": "ns.example.net"
        },
        {
            "name": "ns.example.com",
            "ips": ["192.0.2.1", "2001:db8:3fe:1001:7777:772e:2:85"]
        }
    ],
    "createDate": "2014-01-01",
    "currentContractPeriodEnd": "2015-12-31",
    "nextContractPeriodStart": "2016-01-01",
    "deletionType": "",
    "deletionDate": "",
    "addDate": "2015-01-01T00:00:00",
    "lastChangeDate": "2014-12-15T00:00:00"
}
<domainObject>
 <id>150101000000010</id>
 <accountId>150101000000001</accountId>
 <name>example.com</name>
 <nameUnicode>example.com</nameUnicode>
 <status>
  <item>ok</item>
 </status>
 <transferLockEnabled>false</transferLockEnabled>
 <authInfo>1234,ABCD+xyz</authInfo>
 <contacts>
  <item>
   <contact>150101000000021</contact>
   <type>owner</type>
  </item>
  <item>
   <contact>150101000000020</contact>
   <type>admin</type>
  </item>
  <item>
   <contact>150101000000022</contact>
   <type>tech</type>
  </item>
  <item>
   <contact>150101000000023</contact>
   <type>zone</type>
  </item>
 </contacts>
 <nameservers>
  <item>
   <ips/>
   <name>ns.example.net</name>
  </item>
  <item>
   <ips>
    <item>192.0.2.1</item>
    <item>2001:db8:3fe:1001:7777:772e:2:85</item>
   </ips>
   <name>ns.example.com</name>
  </item>
 </nameservers>
 <createDate>2014-01-01</createDate>
 <currentContractPeriodEnd>2015-12-31</currentContractPeriodEnd>
 <nextContractPeriodStart>2016-01-01</nextContractPeriodStart>
 <deletionDate></deletionDate>
 <deletionType></deletionType>
 <addDate>2015-01-01T00:00:00</addDate>
 <lastChangeDate>2014-12-15T00:00:00</lastChangeDate>
</domainObject>

Domain Object

Property Type Required / Direction Description
id string out-only Domain ID
accountId string out-only ID of account managing domain (field is never used in requests)
name string req Domain name. (Unicode or ASCII format). The name will always be returned in ASCII/ACE format.
nameUnicode string out-only Domain name in Unicode/international format
status string out-only Domain status, cf. below for explanation of statuses
transferLockEnabled bool req If set to true, outgoing transfers will be blocked. Please keep in mind that not every TLD supports this feature.
authInfo string out-only The domain transfer authorisation code for this domain. Only contains a value if transferLockEnabled is not set.
contacts list<DomainContact> req List of contacts for this domain, cf. Domain Contact Object for details
nameservers list<Nameserver> req List of name servers for this domain, cf. Name Server Object for details.
createDate date out-only Date of domain creation. If the domain is transferred in and the registry does not support getting the original creation date, it will be the date of the transfer.
currentContractPeriodEnd date out-only End date of current contract period
nextContractPeriodStart date out-only Start date of next contract period
deletionType string out-only Removal mode (delete or withdraw). Empty when domain is not scheduled for removal.
deletionDate datetime out-only Date the domain is scheduled for deletion or withdrawal. Is empty if domain is not scheduled for removal.
addDate datetime out-only Date and time this domain was created in or transferred into our system.
lastChangeDate datetime out-only Date and time of last modification of any domain data in our system.

DomainContact Object

Property Type Required Description
type string req owner, admin, tech, or zone
contact string req Contact handle or ID in our system. The contact will always be returned as an ID.

Nameserver Object

Property Type Required Description
name string req Fully qualified domain name of name server.
Example: ns1.example.net
ips list<string> cf. description List of IP addresses of this name server. Required for name servers that are subdomains of the domain itself. Otherwise it is ignored.
Examples: “192.0.2.15”, “2001:db8::cafe”, “2001:db8:3fe:1001:7777:772e:2:85”

Domain Status

The following domain statuses are defined:

Domain status Description
ordered Domain is ordered but create or transfer process is not completed yet
active Domain is in customer’s account
restorable Domain was deleted and is in restore grace period
failed Domain is failed; registry will delete the domain if no action is taken

Listing Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainsFind
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "domainNameUnicode",
        "value": "*example.com*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "domainNameUnicode",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>domainNameUnicode</field>
  <value>*example.com*</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>domainNameUnicode</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // domain objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindDomainsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindDomainsResult</type>
 </response>
 ...
</response>
RequestdomainsFind
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainsFind
Processingsynchronous
ResponseFindDomainsResult

When listing domains, you use the generic filtering and sorting API with the method domainsFind. The response will contain a list of Domain objects.

The following fields are available for filtering and sorting:

Field Description
DomainId ID of domain
AccountId ID of domain’s managing account
DomainName Domain name in ACE format
DomainNameUnicode Domain name in Unicode format
DomainStatus Domain Status
DomainCreateDate Creation date in registry
DomainCurrentContractPeriodEnd End date of current domain contract period
DomainNextContractPeriodStart Start date of next domain contract period
DomainTransferLockEnabled Activate blocking transfer outs
DomainDeletionType Delete or withdraw domain. Empty, if domain is not scheduled for removal.
DomainDeletionDate Withdrawal/Deletion date. Empty, if domain is not scheduled for removal.
DomainAddDate Date and time the domain name object was created in our system.
DomainLastChangeDate Date and time the domain name was last modified.
ContactId Match domain names using this contact
DomainContactAllocation Match domain names that use ContactId for this allocation
ContactHandle Handle of a contact connected to the domain name
ContactName Name of a contact connected to the domain name
ContactOrganization Organization of a contact connected to the domain name

Registering New Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainCreate
{
    "authToken": "$$YOUR API KEY$$",
    "domain": {
        "name": "example.com",
        "transferLockEnabled": true,
        "contacts": [
            {
                "contact": "150101000000021",
                "type": "owner"
            },
            {
                "contact": "150101000000020",
                "type": "admin"
            },
            {
                "contact": "150101000000022",
                "type": "tech"
            },
            {
                "contact": "150101000000023",
                "type": "zone"
            }
        ],
        "nameservers": [
            {
                "name": "ns1.example.net"
            },
            {
                "name": "ns2.example.net"
            },
            {
                "name": "ns3.example.com",
                "ip": ["192.0.2.1", "192.0.2.200", "2001:db8:3fe:1001:7777:772e:2:85"]
            }
        ]
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domain>
  <name>example.com</name>
  <transferLockEnabled>true</transferLockEnabled>
  <contacts>
   <item>
    <contact>150101000000021</contact>
    <type>owner</type>
   </item>
   <item>
    <contact>150101000000020</contact>
    <type>admin</type>
   </item>
   <item>
    <contact>150101000000022</contact>
    <type>tech</type>
   </item>
   <item>
    <contact>150101000000023</contact>
    <type>zone</type>
   </item>
  </contacts>
  <nameservers>
   <item>
    <name>ns1.example.net</name>
   </item>
   <item>
    <name>ns2.example.net</name>
   </item>
   <item>
    <ip>
    <name>ns3.example.com</name>
     <item>192.0.2.1</item>
     <item>192.0.2.200</item>
     <item>2001:db8:3fe:1001:7777:772e:2:85</item>
    </ip>
   </item>
  </nameservers>
 </domain>
</request>
Response
{
    ...
    "response": {
        "id": "150101000000010",                    // newly generated id
        "accountId": "150101000000001",             // account id used for creation
        "name": "example.com",                      // domain name translated to Ace form
        "nameUnicode": "example.com",               // domain name translated to Unicode form
        "status": ["api-create-pending"],           // domain registration is running
        // ... as supplied in request, contact handles will be translated to ids
        "createDate": "2014-01-01",                 // always current date for create
        "currentContractPeriodEnd": "2015-12-31",   // provisional value
        "nextContractPeriodStart": "2016-01-01",    // provisional value
        "addDate": "2015-01-01T00:00:00",           // always current date for create
        "lastChangeDate": "2015-01-01T00:00:00"     // always current date and time
    }
}
<response>
 <response>
  <id>150101000000010</id>                                          // newly generated id
  <accountId>150101000000001</accountId>                            // account id used for creation
  <name>example.com</name>                                          // domain name translated to Ace form
  <nameUnicode>example.com</nameUnicode>                            // domain name translated to Unicode form
  <status>                                                          // domain registration is running
   <item>api-create-pending</item>
  </status>
  // ... as supplied in request, contact handles will be translated to ids
  <createDate>2014-01-01</createDate>                               // always current date for create
  <currentContractPeriodEnd>2015-12-31</currentContractPeriodEnd>   // provisional value
  <nextContractPeriodStart>2016-01-01</nextContractPeriodStart>     // provisional value
  <addDate>2015-01-01T00:00:00</addDate>                            // always current date for create
  <lastChangeDate>2015-01-01T00:00:00</lastChangeDate>              // always current date and time
 </response>
</response>
RequestdomainCreate
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainCreate
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domain Domain object req Data for to be created domain

In order to create a domain, you need to send a domainCreate request. This request takes one parameter domain which contains all required information of a domain object.

Each allocation (owner, tech, admin, zone) requires one contact. The system will ensure that only supported contact allocations will be used for registry operations.

The contractPeriod details are provisional values. If the actual registration of the domain is delayed, the contract period will be adjusted accordingly.

Updating Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "domain": {
        "name": "example.com",
        "transferLockEnabled": false,
        "contacts": [
            {
                "contact": "150101000000025",
                "type": "owner"
            },
            {
                "contact": "150101000000024",
                "type": "admin"
            },
            {
                "contact": "150101000000026",
                "type": "tech"
            },
            {
                "contact": "150101000000027",
                "type": "zone"
            }
        ],
        "nameservers": [
            {
                "name": "ns1.great-domains.net"
            },
            {
                "name": "ns2.great-domains.net"
            }
        ]

    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <clientTransactionId></clientTransactionId>
 <domain>
  <name>example.com</name>
  <transferLockEnabled>false</transferLockEnabled>
  <contacts>
   <item>
    <contact>150101000000025</contact>
    <type>owner</type>
   </item>
   <item>
    <contact>150101000000024</contact>
    <type>admin</type>
   </item>
   <item>
    <contact>150101000000026</contact>
    <type>tech</type>
   </item>
   <item>
    <contact>150101000000027</contact>
    <type>zone</type>
   </item>
  </contacts>
  <nameservers>
   <item>
    <name>ns1.great-domains.net</name>
   </item>
   <item>
    <name>ns2.great-domains.net</name>
   </item>
  </nameservers>
 </domain>
</request>
RequestdomainUpdate
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainUpdate
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domain Domain object req Updated domain data
actingAs string opt see below

In order to update a domain, you send a domainUpdate request with a domain object containing the modified properties.

Usually, you need to send a modified version of an object you received from domainInfo or domainsFind.

The modified domain is identified by the id or name property in the supplied domain object. All fields not marked ‘out-only’ are set to the values in the contact argument. Optional fields that are not specified in this request are reset to their default values.

The response will contain the modified domain object.

Changing the owner contact of a domain in a generic extension (com, net, etc) may result in an owner change under the ICANN rules. If this is the case both new and old contact need to confirm the change via emailed confirm code.

By passing designatedAgent as the actingAs parameter you affirm that the current and the new contact have explicitly opted in to authorize you to approve a Change of Registrant on their behalf. Thus the email confirmation will not be needed.

To check if an update is an owner change under ICANN rules (i.e. is material change and affects domains under icann rules) you can use the domainUpdateIsIcannOwnerChange api function.

RequestdomainUpdateIsIcannOwnerChange
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainUpdateIsIcannOwnerChange
Processingsynchronous
Responsebool
Parameter Type Required Description
domain Domain object req domain data to check

Retrieving Specific Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainInfo
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainInfo
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainInfo
Processingsynchronous
ResponseDomain object
Parameter Type Required Description
domainName string req Domain name (ACE or Unicode)

The domainInfo is a shortcut to retrieve data of a domain with a specific name.

Checking Domain Name Availability

POST https://partner.http.net/api/domain/v1/jsonxml/domainStatus
{
    "authToken": "$$YOUR API KEY$$",
    "domainNames": [
        "somedomain.com"
    ]
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainNames>
  <item>somedomain.com</item>
 </domainNames>
</request>
Response
{
    "metadata": { ... },
    "responses": [
        {
            "domainName": "example.com",
            "domainNameUnicode": "example.com",
            "domainSuffix": "com",
            "status": "available",
            "transferMethod": "authInfo"
        }
    ],
    "status": "success",
    "warnings": [ ]
}
<response>
 <metadata>...</metadata>
 <responses>
  <item>
   <domainName>example.com</domainName>
   <domainnameUnicode>example.com</domainNameUnicode>
   <domainSuffix>com</domainSuffix>
   <status>available</status>
   <transferMethod>authInfo</transferMethod>
  </item>
 </responses>
 <status>success</status>
 <warnings/>
</response>
RequestdomainStatus
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainStatus
Processingsynchronous
ResponseDomainStatusResult object
Parameter Type Required Description
domainNames list req Domain names to check either in Unicode or ASCII format.

In order to check whether one or more domain names are available for registration, you only need to pass a list of the domain names you want to check as domainNames parameter.

The response will contain a list of objects of the following type:

DomainStatusResult Object

Property Type direction Description
domainName string out Name of checked domain in ACE format
domainNameUnicode string out Name of checked domain in Unicode format
domainSuffix string out Domain suffix
status string out Result of check
transferMethod string out Transfer method if domain is already registered

The possible domain statuses can be returned to you:

status Description
alreadyRegistered You (or a sub account) already registered the domain
registered Somebody else registered domain
nameContainsForbiddenCharacter Domain name contains invalid characters
available Domain is available for registration
suffixDoesNotExist Domain suffix does not exist
suffixCannotBeRegistered You are not allowed to register a domain with this suffix
canNotCheck System is currently unable to check availability
unknown Other problems or difficulties occured

If the status is registered, the transferMethod will further specify how you can start a transfer in:

transferMethod Description
“” (empty string) Transfer uses out-of-band authentication. In that case, do not specify authInfo in domainTransfer request.
authInfo Transfer uses authInfo. Supply it in domainTransfer request.
push Domain uses push. First start a domainTransfer to pre-authorize domain transfer to your account and then push to our registrar’s tag with the domain’s current supplier.

Deleting Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainDelete
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "somedomain.de"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>somedomain.de</domainName>
</request>
RequestdomainDelete
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainDelete
Processingasynchronous
Responsenone
Parameter Type Required Description
domainName string req Name of the domain to be deleted (Unicode or ASCII format)
execDate string opt Scheduled deletion date

In order to delete a domain, you can use the domainDelete request. Its simplest form only requires domainName as parameter. The domain’s scheduled deletion date is set immediately.

Scheduled delete

POST https://partner.http.net/api/domain/v1/jsonxml/domainDelete
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "somedomain.de",
    "execDate": "2015-01-01T00:00:00Z"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>somedomain.de</domainName>
 <execDate>2015-01-01T00:00:00Z</execDate>
</request>

If you also specify an execDate, it will be scheduled for deletion on execDate. This will change the domain object’s deletionType to delete and set its deletionDate.

Withdrawing Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainWithdraw
{
    "authToken": "$$YOUR API KEY$$",
    "disconnect": false,
    "domainName": "somedomain.de"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <disconnect>false</disconnect>
 <domainName>somedomain.de</domainName>
</request>
RequestdomainWithdraw
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainWithdraw
Processingasynchronous
Responsenone
Parameter Type Required Description
domainName string req Name of the domain to be withdrawn (Unicode or ASCII format)
disconnect bool req Disconnect the domain from name servers after withdrawal
execDate string opt Scheduled withdrawal date

In order to withdraw a domain, you can use the request domainWithdraw. Its simplest form only requiresdomainName and disconnect as parameter. The domain’s withdrawal date is set immediately.

Scheduled withdraw

POST https://partner.http.net/api/domain/v1/jsonxml/domainWithdraw
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.de",
    "execDate": "2015-01-01T00:00:00Z"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.de</domainName>
 <execDate>2015-01-01T00:00:00Z</execDate>
</request>

If you also specify an execDate, it will be scheduled for withdrawal on execDate. This will set the domain object’s deletionType to withdraw and set its deletionDate.

Starting Transfer-Ins

POST https://partner.http.net/api/domain/v1/jsonxml/domainTransfer
{
    "authToken": "$$YOUR API KEY$$",
    "domain": {
        "name": "example.org",
        "transferLockEnabled": true,
        "contacts": [
            {
                "contact": "150101000000021",
                "type": "owner"
            },
            {
                "contact": "150101000000020",
                "type": "admin"
            },
            {
                "contact": "150101000000022",
                "type": "tech"
            },
            {
                "contact": "150101000000023",
                "type": "zone"
            }
        ],
        "nameservers": [
            {
                "name": "ns1.example.net"
            },
            {
                "name": "ns2.example.net"
            },
            {
                "name": "ns3.example.net"
            }
        ]
    },
    "transferData": {
        "authInfo": "1234,ABCD+xyz"
    }
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domain>
  <name>example.org</name>
  <contacts>
   <item>
    <contact>150101000000021</contact>
    <type>owner</type>
   </item>
   <item>
    <contact>150101000000020</contact>
    <type>admin</type>
   </item>
   <item>
    <contact>150101000000022</contact>
    <type>tech</type>
   </item>
   <item>
    <contact>150101000000023</contact>
    <type>zone</type>
   </item>
  </contacts>
  <nameservers>
   <item>
    <name>ns1.example.net</name>
   </item>
   <item>
    <name>ns2.example.net</name>
   </item>
   <item>
    <name>ns3.example.net</name>
   </item>
  </nameservers>
  <transferLockEnabled>true</transferLockEnabled>
 </domain>
 <transferData>
  <authInfo>1234,ABCD+xyz</authInfo>
 </transferData>
</request>
RequestdomainTransfer
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainTransfer
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domain Domain object req Data for transferred domain
transferData TransferData object req Additional transfer settings

TransferData Object

Property Type Required Description
authInfo string opt authInfo / Password for domain Transfer
foaRecipient string opt admin, owner, or both: Which contacts should receive the FOA mail.

Transferring domains with the API is a similar process to registering new domains. Please refer to domainCreate for further details on the domain parameter.

When transferring domains, your request needs a transferData object. For most domains you need to fill the authInfo field with a transfer password obtained from the registrar currently managing that domain.

You can check whether this field is required by using the response from the domainStatus request. If the response’s transferMethod is authInfo, it is needed.

Before requests for certain domain suffixes are processed, the registrar has to check with the current owner and/or administration contact whether the transfer is authorized. For these domain suffixes you can specify which contact shall receive an email to pre-confirm the transfer.

Acknowledging Transfer-Out Requests

POST https://partner.http.net/api/domain/v1/jsonxml/domainTransferOutAck
{
    "authToken": "$$YOUR API KEY$$",
     "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainTransferOutAck
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainTransferOutAck
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domainName string req Name of domain to acknowledge transfer for (Unicode or ASCII format)

The outgoing transfers of certain domain suffixes can be aborted by the registrar currently managing the domain. In that case, a poll message will notify you about the requested transfer. Usually, if you do not send a domainTransferOutNack or domainTransferOutAck in a time period specified by the registry, the transfer out will automatically be approved.

To reject the transfer out, you can simply send a domainTransferOutNack request for the domain. Keep in mind that there are registry-specific restrictions which specify the permitted cases.

POST https://partner.http.net/api/domain/v1/jsonxml/domainTransferOutNack
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainTransferOutNack
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainTransferOutNack
Processingasynchronous
ResponseDomain object
Parameter Type Required Description
domainName string req Name of the domain to reject transfer for (Unicode or ASCII format)

If you want the outgoing transfer to proceed, you can explicitly send a domainTransferOutAck request to reduce the time until the transfer out is completed.

Restoring Deleted Domains

POST https://partner.http.net/api/domain/v1/jsonxml/domainRestore
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainRestore
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainRestore
Processingasynchronous
Response-
Parameter Type Required Description
domainName string req Name of the domain you want to restore (Unicode or ASCII format)

When a domain is in restorable state, you can restore it by using the domainRestore request.

Requesting Auth-Info2 (.de)

POST https://partner.http.net/api/domain/v1/jsonxml/domainCreateAuthInfo2
{
    "authToken": "$$YOUR API KEY$$",
    "domainName": "example.com"
}
<request>
 <authToken>$$YOUR API KEY$$</authToken>
 <domainName>example.com</domainName>
</request>
RequestdomainCreateAuthInfo2
Urlhttps://partner.http.net/api/domain/v1/jsonxml/domainCreateAuthInfo2
Processingasynchronous
Response-
Parameter Type Required Description
domainName string req Name of the domain that the auth-info 2 is requested for (Unicode or ASCII format)

For .de domains there is an additional transfer authorization password. DeNIC will send it via mail to the current domain owner. It can be requested by any registrar. If you want to initiate this process, you need to send a domainCreateAuthInfo2 request.

You can even send this request for domains that are not in your account.

Job Object

{
    "id": "150223248499677",
    "accountId": "15010100000001",
    "displayName": "example.org",
    "domainNameAce": "example.org",
    "domainNameUnicode": "example.org",
    "handle": "",
    "type": "domainTransferIn",
    "state": "error",
    "subState": "",
    "comments": "",
    "errors": "[{\"code\":30003,\"context\":\"example.org\",\"details\":[],\"text\":\"The provided Authinfo is wrong\"}]",
    "executionDate": "2015-02-23T17:39:23Z",
    "addDate": "2015-01-01T00:00:00Z",
    "lastChangeDate": "2015-01-01T00:00:00Z"
}
<job>
 <id>150223248499677</id>
 <accountId>1</accountId>
 <displayName>example.org</displayName>
 <domainNameAce>example.org</domainNameAce>
 <domainNameUnicode>example.org</domainNameUnicode>
 <handle></handle>
 <type>domainTransferIn</type>
 <state>error</state>
 <subState></subState>
 <comments></comments>
 <errors>[{"code":30003,"context":"example.org","details":[],"text":"The provided Authinfo is wrong"}]</errors>
 <executionDate>2015-02-23T17:39:23Z</executionDate>
 <addDate>2015-01-01T00:00:00Z</addDate>
 <lastChangeDate>2015-01-01T00:00:00Z</lastChangeDate>
</job>

Job Object

Property Type Required / Direction Description
id string out-only Job ID
accountId string out-only ID of account, the job was executed for (usually owner of the object the job belongs to)
type string out-only Type of job
displayName string out-only Either domainNameUnicode or handle, depending on which is set
domainNameAce string out-only Domain name in ACE format
domainNameUnicode string out-only Domain name in Unicode format
handle string out-only Contact Handle
state string out-only State of job
errors string out-only JSON encoded list of errors encountered while executing this job
warnings strnig out-only JSON encoded list of warnings encountered while executing this job
clientTransactionId string out-only Client transaction ID used in request
serverTransactionId string out-only Server transaction ID created for request
executionDate datetime out-only Date and time job was or will be executed
addDate datetime out-only Date and time job object was created
lastChangeDate datetime out-only Date and time job was last modified

Listing Jobs

RequestjobsFind
Urlhttps://partner.http.net/api/domain/v1/jsonxml/jobsFind
Processingsynchronous
ResponseFindJobsResult

In order to list jobs, you use the generic filtering and sorting API with the jobsFind method. The response will contain a list of Job objects.

The following fields are available for filtering and sorting:

Field Description
AccountId Account ID associated with job
JobId ID of job
JobType Job type, e.g. domainCreate or contactUpdate
JobDisplayName May contain handle or domainNameUnicode (cf. Job object)
JobDomainName Domain name in ACE format
JobDomainNameUnicode Domain name in Unicode format
JobHandle Contact handle string
JobState State of job
JobSubState Substate of job
JobComments Comments of job
JobAddDate Date and time job was created
JobLastChangeDate Date and time job was last modified
JobExecutionDate Date and time job was or will be executed
JobClientTransactionId Client transaction ID used in request
JobServerTransactionId Server transaction ID created for request

DNS

The ZoneConfig Object

ZoneConfig Object

The ZoneConfig object defines a zone.

Property Type Required Description
id string see description ID of this zoneConfig. Ignored in zone create requests. Either id or name is required in all other requests.
accountId string out-only ID of the account that manages the zone. This property is never used in requests.
status string out-only Current status of the Zone
name string see description The zone name in ACE format. name is always required in zone create requests and all other requests if no id is provided. While you may use this property for a Unicode zone name, the responses will always contain the ACE encoded zone.
nameUnicode string opt The zone name in Unicode. If it is left empty it will be filled automatically based on name.
masterIp string see description A valid IPv4 or IPv6 must be provided if the type is SLAVE. If the type is NATIVE or MASTER the field must be empty.
type string req Valid types are NATIVE, MASTER, and SLAVE
emailAddress string opt The hostmaster email address. Only relevant if the type is NATIVE or MASTER. If the field is left empty, the default is hostmaster@name.
zoneTransferWhitelist list<string> opt List of IP addresses whitelisted for zone transfers. Only allowed if the type is MASTER. Must contain valid IPv4 or IPv6 addresses.
lastChangeDate datetime out-only Date and time the zone was last modified
soaValues SoaValues opt Values for the SOA record of the zone. If it is left empty an SOA record with default values will be created.
templateValues TemplateValues opt This property can be used if you want to create the zone with a template.

The Template Values Object

TemplateValues Object

The template values object can be used to create or recreate a zone using a template.

All record templates connected to the template will be converted into records for the zone. These record templates may contain placeholders. A replacement value has to be provided for each placeholder that is used in the template. Otherwise you will receive an error.

The zone may be tied to the used template. A zone that is tied to a template will receive updates automatically.

Cf. The Template Object for more details.

Property Type Required Description
templateId string opt ID of the template
templateName string out-only Name of the used template
tieToTemplate bool opt Tie the zone to the template
templateReplacements TemplateReplacements opt Replacement values for the placeholders

The Template Replacements Object

TemplateReplacements Object

The template replacements object is used for recreating and updating templates.

Whenever a template is changed, all zones that are tied to the template are changed as well. If, for example, you add a new record template that contains a placeholder that has not been used in the template before, the zones tied to the template might not have a replacement value for the placeholder.

In that case the replacement value provided with the Template Replacements Object will be used as a default.

Property Type Required Description
ipv4Replacement string opt
ipv6Replacement string opt
mailIpv4Replacement string opt
mailIpv6Replacement string opt

The SOA Values Object

SoaValues Object

The SOA values object contains the time (seconds) used in a zone’s SOA record. The maximum number of seconds is 31556926 which equals one year. Exceeding the maximum and uncercutting the minimum values will cause the request to be aborted and create an error.

Property Type Required Description
refresh int req Refresh for the SOA record. Default: 86400, minimum: 3600.
retry int req Retry for the SOA record. Default: 7200, minimum: 600.
expire int req Expire for the SOA record. Default: 3600000, minimum: 86400.
ttl int req TTL for the SOA record. Default: 172800, minimum: 60.
negativeTtl int req Negative TTL for the SOA record. Default: 3600, minimum: 60.

The Record Object

DnsRecord Object

The DNS Record object is part of a zone. It is used to manage DNS resource records.

Property Type Required Description
id string see description Record ID. Ignored in create zone requests. Either id or zoneId, name, type, and content are required in all other requests.
zoneId string out-only ID of zone that the record belongs to.
recordTemplateId string opt ID of record template the record is tied to. If empty, record has to be managed manually. If tied to record template, record will be removed or updated whenever record template is removed or updated.
name string see description Name of the record. Example: mail.example.com. Always required in create requests and in all other requests if no id is provided.
type string see description Type of the record. Valid types are A, AAAA, MX, NS, CNAME, PTR, and SRV. Always required in create requests and in all other requests if no id is provided.
content string see description Content of the record. Always required in create requests and in all other requests if no id is provided.
ttl int opt TTL of the record in seconds. Minimum value: 60. Maximum value: 31556926 (one year). Exceeding the maximum or undercutting the minimun value will abort the request and result in an error.
priority int opt Priority of record. Only relevant if type is MX or SRV. Must be positive.
lastChangeDate datetime out-only Date and time of last record modification

The Zone Object

Zone Object

A Zone consists of a Zone Configuration and a list of DNS records and represents the DNS zone.

A Zone object is the result of a zonesFind request.

Property Type Required Description
zoneConfig ZoneConfig out-only
records list<DnsRecord> out-only

List ZoneConfigs

POST https://partner.http.net/api/dns/v1/jsonxml/zoneConfigsFind
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "ZoneNameUnicode",
        "value": "*example.com*"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "ZoneNameUnicode",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <item>
   <field>ZoneNameUnicode</field>
   <value>*example.com*</value>
  </item>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>ZoneNameUnicode</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // zoneConfig objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindZoneConfigsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindZoneConfigsResult</type>
 </response>
 ...
</response>
RequestzoneConfigsFind
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zoneConfigsFind
Processingsynchronous
ResponseFindZoneConfigsResult

Listing zoneConfigs uses the generic filtering and sorting API with the method zoneConfigsFind. The response will contain a list of ZoneConfig objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of the account that the zone belongs to
ZoneConfigId ZoneConfig object ID
ZoneName Zone name in ACE format
ZoneNameUnicode Zone name in Unicode format
ZoneMasterIp Master IP address of the zone
ZoneType Zone type (“MASTER”, “NATIVE”, or “SLAVE”)
ZoneEmailAddress Email address of hostmaster
ZoneLastChangeDate Date and time of last zone update
ZoneSoaRefresh SOA refresh interval of slaves (seconds)
ZoneSoaRetry SOA retry interval of slaves (seconds)
ZoneSoaExpire SOA deactivation timeout of slaves (seconds)
ZoneSoaTtl SOA time to live for negative caching (seconds)
ZoneIpv4Replacement Replacement value for ##IPv4## placeholder in template
ZoneIpv6Replacement Replacement value for ##IPv6## placeholder in template
ZoneMailIpv4Replacement Replacement value for ##IPv4## mail addresses in template
ZoneMailIpv6Replacement Replacement value for ##IPv6## mail addresses in template
TemplateName Name of template associated with zone
TemplateId ID of template associated with zone

Listing Records

POST https://partner.http.net/api/dns/v1/jsonxml/recordsFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "zoneConfigId",
        "value": "15010100000010"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "recordName",
        "order": "asc"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <item>
   <field>zoneConfigId</field>
   <value>15010100000010</value>
  </item>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>recordName</field>
  <order>asc</order>
 </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // record objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindRecordsResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindRecordsResult</type>
 </response>
 ...
</response>
RequestrecordsFind
Urlhttps://partner.http.net/api/dns/v1/jsonxml/recordsFind
Processingsynchronous
ResponseFindRecordsResult

Listing DNS records uses the generic filtering and sorting API with the method recordsFind. The response will contain a list of record objects.

The following fields are available for filtering and sorting:

Field Description
ZoneConfigId ID of the zoneConfig object to which the record belongs
RecordId Record object ID
RecordName Name of the record
RecordType Type of the record
RecordContent Content of the record
RecordTtl Time to live (in seconds)
RecordPriority Priority of the record (integer)
RecordLastChangeDate Date and time of last modification

Listing Zones

POST https://partner.http.net/api/dns/v1/jsonxml/zonesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "accountId",
        "value": "150101000000001"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "zoneName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>accountId</field>
    <value>150101000000001</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>zoneName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // zone objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindZonesResult"
    },
    ...
}
<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindZonesResult</type>
 </response>
 ...
</response>
RequestzonesFind
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zonesFind
Processingsynchronous
ResponseFindZonesResult

Listing zones uses the generic filtering and sorting API with the method zonesFind. The response will contain a list of Zone Objects that consist of a zoneConfig and all its records.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of the account to which the zone belongs
ZoneConfigId ID of the zoneConfig object
ZoneName Zone name in ACE format
ZoneNameUnicode Zone name in Unicode format
ZoneMasterIp Master IP address of the zone
ZoneType Zone type (“MASTER”, “NATIVE”, or “SLAVE”)
ZoneEmailAddress Email address of the zone
ZoneLastChangeDate Time and date of last modification
ZoneSoaRefresh SOA refresh interval of slaves (seconds)
ZoneSoaRetry SOA retry interval of slaves (seconds)
ZoneSoaExpire SOA deactivation timeout of slaves (seconds)
ZoneSoaTtl SOA time to live for negative caching (seconds)
ZoneIpv4Replacement Replacement value for IPv4 addresses in template
ZoneIpv6Replacement Replacement value for IPv6 addresses in template
ZoneMailIpv4Replacement Replacement value for IPv4 mail addresses in template
ZoneMailIpv6Replacement Replacement value for IPv6 mail addresses in template
TemplateName Name of template associated with zone
TemplateId ID of template associated with zone
RecordId ID of record in zone
RecordName Name of record in zone
RecordType Type of record in zone
RecordContent Content of record in zone
RecordTtl Time to live (in seconds)
RecordPriority Priority of record in zone (integer)
RecordLastChangedate Date and time of last modification in zone

Creating New Zones

POST https://partner.http.net/api/dns/v1/jsonxml/zoneCreate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSetId": "15010100000020",
    "useDefaultNameserverSet": false,
    "zoneConfig": {
            "name": "example.com",
            "type": "NATIVE",
            "emailAddress": "admin@example.com"
    },
    "records": [
        {
            "name": "www.example.com",
            "type": "A",
            "content": "172.27.171.106",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "smtp.example.com",
            "ttl": 86000
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSetId>15010100000020</nameserverSetId>
  <records>
    <item>
      <content>172.27.171.106</content>
      <name>www.example.com</name>
      <ttl>86000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </records>
  <useDefaultNameserverSet>false</useDefaultNameserverSet>
  <zoneConfig>
    <emailAddress>admin@example.com</emailAddress>
    <name>example.com</name>
    <type>NATIVE</type>
  </zoneConfig>
</request>
Response
{
    ...
    "response": {
        "records": [
            {
                "content": "172.27.171.106",
                "id": "15010100000020",
                "lastChangeDate": "2015-09-02",
                "name": "www.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "A",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "smtp.example.com",
                "id": "15010100000021",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": 0,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "MX",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns2.example.com",
                "id": "15010100000022",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com",
                "id": "15010100000023",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com. admin.example.com. 2015090201 86400 7200 3600000 172800",
                "id": "15010100000024",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "SOA",
                "zoneConfigId": "15010100000010"
            }
        ],
        "zoneConfig": {
            "accountId": "15010100000001",
            "emailAddress": "admin@example.com",
            "id": "15010100000010",
            "lastChangeDate": "2015-09-02T09:42:08Z",
            "masterIp": "",
            "name": "example.com",
            "nameUnicode": "example.com",
            "soaValues": {
                "expire": 3600000,
                "negativeTtl": 3600,
                "refresh": 86400,
                "retry": 7200,
                "serial": null,
                "ttl": 172800
            },
            "status": "blocked",
            "templateValues": null,
            "type": "NATIVE",
            "zoneTransferWhitelist": [
            ]
        }
    },
    ...
}
<response>
  ...
  <response>
    <records>
      <item>
        <content>172.27.171.106</content>
        <id>15010100000020</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>www.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>A</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>smtp.example.com</content>
        <id>15010100000021</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority>0</priority>
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>MX</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns2.example.com</content>
        <id>15010100000022</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com</content>
        <id>15010100000023</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com. admin.example.com. 2015090201 86400 7200 3600000 172800</content>
        <id>15010100000024</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>SOA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
    </records>
    <zoneConfig>
      <accountId>15010100000001</accountId>
      <emailAddress>admin@example.com</emailAddress>
      <id>15010100000010</id>
      <lastChangeDate>2015-09-02T09:42:08Z</lastChangeDate>
      <masterIp />
      <name>example.com</name>
      <nameUnicode>example.com</nameUnicode>
      <soaValues>
        <expire>3600000</expire>
        <negativeTtl>3600</negativeTtl>
        <refresh>86400</refresh>
        <retry>7200</retry>
        <serial null="true" />
        <ttl>172800</ttl>
      </soaValues>
      <status>blocked</status>
      <templateValues null="true" />
      <type>NATIVE</type>
      <zoneTransferWhitelist />
    </zoneConfig>
  </response>
  ...
</response>
RequestzoneCreate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zoneCreate
Processingsynchronous
ResponseZone
Parameter Type Required Description
zoneConfig ZoneConfig req zoneConfig of the zone
records list<Record> req Records of the zone
nameserverSetId string opt NameserverSet to use for automatic creation of NS records. Default: 0
useDefaultNameserverSet bool opt Use your account’s default nameserver set. Default: false

To create a zone, you need at least a zoneConfig.

A zone may be created manually or from a template. If you want to use a template, you have to at least provide a template ID in the zoneConfig’s template values property. See template object for more details.

See NameserverSet object for more details on using nameserver sets.

Recreating Existing Zones

POST https://partner.http.net/api/dns/v1/jsonxml/zoneRecreate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSetId": "15010100000020",
    "useDefaultNamserverSet": false,
    "zoneConfig": {
            "name": "example.com",
            "nameUnicode": "example.com",
            "type": "NATIVE",
            "emailAddress": "admin@example.com"
    },
    "records": [
        {
            "name": "www.example.com",
            "type": "A",
            "content": "172.27.171.106",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "smtp.example.com",
            "ttl": 86000
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSetId>15010100000020</nameserverSetId>
  <records>
    <item>
      <content>172.27.171.106</content>
      <name>www.example.com</name>
      <ttl>86000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </records>
  <useDefaultNamserverSet>false</useDefaultNamserverSet>
  <zoneConfig>
    <emailAddress>admin@example.com</emailAddress>
    <name>example.com</name>
    <nameUnicode>example.com</nameUnicode>
    <type>NATIVE</type>
  </zoneConfig>
</request>
Response
{
    ...
    "response": {
        "records": [
            {
                "content": "ns1.example.com. admin.example.com. 2015090202 86400 7200 3600000 172800",
                "id": "15010100000020",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "SOA",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com",
                "id": "15010100000021",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns2.example.com",
                "id": "15010100000022",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "smtp.example.com",
                "id": "15010100000023",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": 0,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "MX",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "172.27.171.106",
                "id": "15010100000024",
                "lastChangeDate": "2015-09-02",
                "name": "www.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "A",
                "zoneConfigId": "15010100000010"
            }
        ],
        "zoneConfig": {
            "accountId": "15010100000001",
            "emailAddress": "admin@example.com",
            "id": "15010100000010",
            "lastChangeDate": "2015-09-02T09:50:48Z",
            "masterIp": "",
            "name": "example.com",
            "nameUnicode": "example.com",
            "soaValues": {
                "expire": 3600000,
                "negativeTtl": 3600,
                "refresh": 86400,
                "retry": 7200,
                "serial": null,
                "ttl": 172800
            },
            "status": "blocked",
            "templateValues": null,
            "type": "NATIVE",
            "zoneTransferWhitelist": [
            ]
        }
    },
    ...
}
<response>
  ...
  <response>
    <records>
      <item>
        <content>ns1.example.com. admin.example.com. 2015090202 86400 7200 3600000 172800</content>
        <id>15010100000020</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>SOA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com</content>
        <id>15010100000021</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns2.example.com</content>
        <id>15010100000022</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>smtp.example.com</content>
        <id>15010100000023</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority>0</priority>
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>MX</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>172.27.171.106</content>
        <id>15010100000024</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>www.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>A</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
    </records>
    <zoneConfig>
      <accountId>15010100000001</accountId>
      <emailAddress>admin@example.com</emailAddress>
      <id>15010100000010</id>
      <lastChangeDate>2015-09-02T09:50:48Z</lastChangeDate>
      <masterIp />
      <name>example.com</name>
      <nameUnicode>example.com</nameUnicode>
      <soaValues>
        <expire>3600000</expire>
        <negativeTtl>3600</negativeTtl>
        <refresh>86400</refresh>
        <retry>7200</retry>
        <serial null="true" />
        <ttl>172800</ttl>
      </soaValues>
      <status>blocked</status>
      <templateValues null="true" />
      <type>NATIVE</type>
      <zoneTransferWhitelist />
    </zoneConfig>
  </response>
  ...
</response>
RequestzoneRecreate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zoneRecreate
Processingsynchronous
ResponseZone
Parameter Type Required Description
zoneConfig zoneConfig object req ZoneConfig of the zone you want to recreate
records list<Record> req New records of the zone
nameserverSetId string opt NameserverSet to use for automatic creation of NS records. Default: 0
useDefaultNameserverSet bool opt Use your accounts default nameserver set. Default: false

Recreating an existing zone will cause it (ie. the zoneConfig and all records) to be deleted and then created anew with the values and records provided with the request. That means, the zoneConfig has to exist. Calling zoneRecreate with a zoneConfig that does not exist will result in an error.

As in creating a zone, a template may be used. Cf. template object for more details.

See NameserverSet object for more details on using NameserverSets.

Updating Zones

POST https://partner.http.net/api/dns/v1/jsonxml/zoneUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfig": {
        "name": "example.com"
    },
    "recordsToAdd": [
        {
            "name": "www.example.com",
            "type": "AAAA",
            "content": "2001:db8::1",
            "ttl": 86000
        },
        {
            "name": "example.com",
            "type": "MX",
            "content": "newmailserver.example.com",
            "ttl": 86000
        }
    ],
    "recordsToDelete": [
        {
            "name": "example.com",
            "type": "MX",
            "content": "smtp.example.com"
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <recordsToAdd>
    <item>
      <content>2001:db8::1</content>
      <name>www.example.com</name>
      <ttl>86000</ttl>
      <type>AAAA</type>
    </item>
    <item>
      <content>newmailserver.example.com</content>
      <name>example.com</name>
      <ttl>86000</ttl>
      <type>MX</type>
    </item>
  </recordsToAdd>
  <recordsToDelete>
    <item>
      <content>smtp.example.com</content>
      <name>example.com</name>
      <type>MX</type>
    </item>
  </recordsToDelete>
  <zoneConfig>
    <name>example.com</name>
  </zoneConfig>
</request>
Response
{
    ...
    "response": {
        "records": [
            {
                "content": "ns1.example.com",
                "id": "15010100000020",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns1.example.com. admin.example.com. 2015090203 86400 7200 3600000 172800",
                "id": "150902246197317",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "SOA",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "ns2.example.com",
                "id": "15010100000021",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 172800,
                "type": "NS",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "2001:db8::1",
                "id": "15010100000022",
                "lastChangeDate": "2015-09-02",
                "name": "www.example.com",
                "priority": null,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "AAAA",
                "zoneConfigId": "15010100000010"
            },
            {
                "content": "newmailserver.example.com",
                "id": "15010100000023",
                "lastChangeDate": "2015-09-02",
                "name": "example.com",
                "priority": 0,
                "recordTemplateId": null,
                "ttl": 86000,
                "type": "MX",
                "zoneConfigId": "15010100000010"
            }
        ],
        "zoneConfig": {
            "accountId": "15010100000001",
            "emailAddress": "admin@example.com",
            "id": "15010100000010",
            "lastChangeDate": "2015-09-02T10:14:02Z",
            "masterIp": "",
            "name": "example.com",
            "nameUnicode": "example.com",
            "soaValues": {
                "expire": 3600000,
                "negativeTtl": 3600,
                "refresh": 86400,
                "retry": 7200,
                "serial": null,
                "ttl": 172800
            },
            "status": "blocked",
            "templateValues": null,
            "type": "NATIVE",
            "zoneTransferWhitelist": [
            ]
        }
    },
    ...
}
<response>
 ...
  <response>
    <records>
      <item>
        <content>ns1.example.com</content>
        <id>15010100000020</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns1.example.com. admin.example.com. 2015090203 86400 7200 3600000 172800</content>
        <id>150902246197317</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>SOA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>ns2.example.com</content>
        <id>15010100000021</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>172800</ttl>
        <type>NS</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>2001:db8::1</content>
        <id>15010100000022</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>www.example.com</name>
        <priority null="true" />
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>AAAA</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
      <item>
        <content>newmailserver.example.com</content>
        <id>15010100000023</id>
        <lastChangeDate>2015-09-02</lastChangeDate>
        <name>example.com</name>
        <priority>0</priority>
        <recordTemplateId null="true" />
        <ttl>86000</ttl>
        <type>MX</type>
        <zoneConfigId>15010100000010</zoneConfigId>
      </item>
    </records>
    <zoneConfig>
      <accountId>15010100000001</accountId>
      <emailAddress>admin@example.com</emailAddress>
      <id>15010100000010</id>
      <lastChangeDate>2015-09-02T10:14:02Z</lastChangeDate>
      <masterIp />
      <name>example.com</name>
      <nameUnicode>example.com</nameUnicode>
      <soaValues>
        <expire>3600000</expire>
        <negativeTtl>3600</negativeTtl>
        <refresh>86400</refresh>
        <retry>7200</retry>
        <serial null="true" />
        <ttl>172800</ttl>
      </soaValues>
      <status>blocked</status>
      <templateValues null="true" />
      <type>NATIVE</type>
      <zoneTransferWhitelist />
    </zoneConfig>
  </response>
  ...
</response>
RequestzoneUpdate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zoneUpdate
Processingsynchronous
ResponseZone
Parameter Type Required Description
zoneConfig zoneConfig object req zoneConfig to be updated
recordsToAdd list<Record> req Records to be added
recordsToDelete list<Record> req Records to be deleted

You can use zoneUpdate to make adjustments to the zone’s zoneConfig, to remove records, or to add new records. All records in recordsToAdd will be added to the zone, while all records in recordsToDelete will be deleted. If you insert a record that does not exist into recordsToDelete, an error will occur.

Existing records that are not contained in either list will not be changed. So, in order to make adjustments to a record, the original record has to be contained in recordsToDelete and the adjusted version in recordsToAdd.

Deleting Zones

POST https://partner.http.net/api/dns/v1/jsonxml/zoneDelete
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigId": "15010100000010"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigId>15010100000010</zoneConfigId>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestzoneDelete
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zoneDelete
Processingsynchronous
Responseempty
Parameter Type Required Description
zoneConfigId string opt ID of ZoneConfig to be deleted
zoneName string opt Name of ZoneConfig to be deleted

The complete zone, ie. the zoneConfig and all records, will be deleted. Either the ID or the name has to be provided. If both are set, an error will be returned.

Changing Content of Records

POST https://partner.http.net/api/dns/v1/jsonxml/changeContent
{
    "authToken": "$$YOUR API KEY$$",
    "recordType": "MX",
    "oldContent": "mail.mailserver.com",
    "newContent": "mail.smtpservice.com",
    "includeTemplates": false,
    "includeSubAccounts": true
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <includeSubAccounts>true</includeSubAccounts>
  <includeTemplates>false</includeTemplates>
  <newContent>mail.smtpservice.com</newContent>
  <oldContent>mail.mailserver.com</oldContent>
  <recordType>MX</recordType>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestchangeContent
Urlhttps://partner.http.net/api/dns/v1/jsonxml/changeContent
Processingasynchronous
Responseempty
Parameter Type Required Description
recordType string req Type of the records to be changed
oldContent string req Search string for record content
newContent string req Replacement content
includeTemplates bool req Replace content of matching record templates as well
includeSubAccounts bool req Replace values in records of zones belonging to subaccounts

changeContent is a tool for bulk updates to multiple zones.

An example: You use the same mailserver for all your zones and it changed. Instead of performing an update of each zone you just use changeContent with the recordType set to MX, oldContent to the old mailserver, and newContent to the new one.

The change will affect all zones with records that match the recordType and oldContent, but no records that were created with templates. If you want those records and their record templates to be affected as well, you just need to set includeTemplates to true.

If includeSubAccounts is true, the change will affect all matching zones managed by your account and the respective subaccounts as well.

Please note that changeContent is currently asynchronous and may take several minutes, depending on how many zones contain a matching record.

Untying Zones From Their Templates

POST https://partner.http.net/api/dns/v1/jsonxml/zonesUntieFromTemplates
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigIds": [
        "15010100000010"
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigIds>
    <item>15010100000010</item>
  </zoneConfigIds>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestzonesUntieFromTemplates
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zonesUntieFromTemplates
Processingsynchronous
Responseempty
Parameter Type Required Description
zoneConfigIds string req IDs of ZoneConfigs to be detached
zoneConfigNames string req Names of ZoneConfigs to be detached

This will untie a zone from the template it was created from. Afterwards, changes to the template will not affect the zone any longer. Cf. template object for more details.

Either the ID list or the name list has to be provided. If both are set, an error will be returned.

Tying Zones to Templates

POST https://partner.http.net/api/dns/v1/jsonxml/zonesTieToTemplates
{
    "authToken": "$$YOUR API KEY$$",
    "zoneConfigIds": [
        "15010100000010"
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <zoneConfigIds>
    <item>15010100000010</item>
  </zoneConfigIds>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestzonesTieToTemplates
Urlhttps://partner.http.net/api/dns/v1/jsonxml/zonesTieToTemplates
Processingsynchronous
Responseempty
Parameter Type Required Description
zoneConfigIds string req IDs of ZoneConfigs to be detached
zoneConfigNames string req Names of ZoneConfigs to be detached

This will tie a zone to a template. Afterwards all changes to the template will affect the zone. Cf. template object for more details.

New records will be created for all record templates that belong to the template. Should one of these records and an already existing record be identical (i.e. name, type, and content are equal), the old record will be deleted. Either the ID list or the name list has to be provided. If both are set, an error will be returned.

NameserverSet Object

{
    "id": "",
    "accountId": "",
    "name": "Server 1",
    "defaultNameserverSet": false,
    "nameservers": ["ns1.example.com", "ns2.example.com"]
}
<request>
  <accountId />
  <defaultNameserverSet>false</defaultNameserverSet>
  <id />
  <name>Server 1</name>
  <nameservers>
    <item>ns1.example.com</item>
    <item>ns2.example.com</item>
  </nameservers>
</request>

NameserverSet Object

The NameserverSet object is used to manage NameserverSets.

NameserverSets serve a similar purpose to templates: You can create sets for different name server configurations. Then only the ID of the name server set you wish to use for your NS records is needed when creating or recreating a zone. This means you do not need to create the NS records manually.

When you create or recreate a Zone there are two relevant parameters: nameserverSetId and useDefaultNameserverSet.

If useDefaultNameserverSet is set to true, you do not need to provide a nameserverSetId. If you still provide the ID, it will be ignored and the NameserverSet that is marked as default will be used.

If useDefaultNameserverSet is set to false, you may provide a nameserverSetId. If you do so, the NameserverSet with that ID will be used.

If useDefaultNameserverSet is set to false and you do not provide a nameserverSetId or set it to 0, no NameserverSet will be used. In that case, you have to provide at least two NS records for the zone.

Property Type Required Description
id string out-only NameserverSet ID. Ignored in NameserverSet create requests.
accountId string out-only ID of account managing NameserverSet
name string req Name NameserverSet
defaultNameserverSet bool opt If true, this set will be used
nameservers list <string> req List of all name servers in the set. The first entry will be used as primary for the SOA record. Must contain at least two entries.

List Nameserver Sets

POST https://partner.http.net/api/dns/v1/jsonxml/nameserverSetsFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "nameserverSetName",
        "value": "my nameserver set"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "nameserverSetName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>nameserverSetName</field>
    <value>my nameserver set</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>nameserverSetName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // nameserver set objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindNameserverSetsResult"
    },
    ...
}
<response>
  <response>
    <data>
        // nameserver set objects
    </data>
    <limit>10</limit>
    <page>1</page>
    <totalEntries>15</totalEntries>
    <totalPages>2</totalPages>
    <type>FindNameserverSetsResult</type>
  </response>
</request>
RequestnameserverSetsFind
Urlhttps://partner.http.net/api/dns/v1/jsonxml/nameserverSetsFind
Processingsynchronous
ResponseFindNameserverSetsResult

Listing NameserverSets uses the generic filtering and sorting API with the method nameserverSetsFind. The response will contain a list of NameserverSet objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of account managing NameserverSet
NameserverSetId ID of NameserverSet object
NameserverSetName Name of NameserverSet
NameserverSetDefaultNameserverSet True, if default NameserverSet is used (boolean)

Creating NameserverSet

POST https://partner.http.net/api/dns/v1/jsonxml/nameserverSetCreate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSet": {
        "name": "Server 1",
        "defaultNameserverSet": false,
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSet>
    <defaultNameserverSet>false</defaultNameserverSet>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </nameserverSet>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "defaultNameserverSet": false,
        "id": "15010100000010",
        "name": "Server 1",
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    ...
}
<response>
  <response>
    <accountId>15010100000001</accountId>
    <defaultNameserverSet>false</defaultNameserverSet>
    <id>15010100000010</id>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </response>
</request>
RequestnameserverSetCreate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/nameserverSetCreate
Processingsynchronous
ResponseNameserverSet
Parameter Type Required Description
nameserverSet NameserverSet req NameserverSet object to be created

Creates a new NameserverSet.

Updating NameserverSets

POST https://partner.http.net/api/dns/v1/jsonxml/nameserverSetUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSet": {
        "name": "Server 1",
        "defaultNameserverSet": true,
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSet>
    <defaultNameserverSet>true</defaultNameserverSet>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </nameserverSet>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "defaultNameserverSet": true,
        "id": "15010100000010",
        "name": "Server 1",
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    ...
}
<response>
  <response>
    <accountId>15010100000001</accountId>
    <defaultNameserverSet>false</defaultNameserverSet>
    <id>15010100000010</id>
    <name>Server 1</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </response>
</request>
RequestnameserverSetUpdate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/nameserverSetUpdate
Processingsynchronous
ResponseNameserverSet
Parameter Type Required Description
nameserverSet NameserverSet req NameserverSet object to be updated

Updates an existing NameserverSet. If the set does not exist, an error will be returned.

Deleting NameserverSets

POST https://partner.http.net/api/dns/v1/jsonxml/nameserverSetDelete
{
    "authToken": "$$YOUR API KEY$$",
    "nameserverSetId": "15010100000010"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <nameserverSetId>15010100000010</nameserverSetId>
</request>
Response
{
    ...
    "status": "success",
    ...
}
...
    <status>success</status>
    ...
RequestnameserverSetDelete
Urlhttps://partner.http.net/api/dns/v1/jsonxml/nameserverSetDelete
Processingsynchronous
Responseempty
Parameter Type Required Description
nameserverSetId string req ID of NameserverSet to be deleted

Deletes an existing NameserverSet. If the set does not exist, an error will be returned.

Getting Default NameserverSet

POST https://partner.http.net/api/dns/v1/jsonxml/nameserverSetGetDefault
{
    "authToken": "$$YOUR API KEY$$"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
</request>
Response
{
    ...
    "response": {
        "accountId": "15010100000001",
        "defaultNameserverSet": true,
        "id": "15010100000010",
        "name": "Default",
        "nameservers": ["ns1.example.com", "ns2.example.com"]
    },
    ...
}
<response>
  <response>
    <accountId>15010100000001</accountId>
    <defaultNameserverSet>true</defaultNameserverSet>
    <id>15010100000010</id>
    <name>Default</name>
    <nameservers>
      <item>ns1.example.com</item>
      <item>ns2.example.com</item>
    </nameservers>
  </response>
</request>
RequestnameserverSetGetDefault
Urlhttps://partner.http.net/api/dns/v1/jsonxml/nameserverSetGetDefault
Processingsynchronous
ResponseNameserverSet

No specific parameters need to be passed.

This returns the NameserverSet that is used whenever you do not provide a specific NameserverSet ID while creating a zone.

The Template Object

Template Object

The template itself is a simple object only consisting of a name. However, templates are a powerful tool for creating and mass updating zones - quickly and easily.

There are two ways to create or recreate a zone. You can either create the zone by providing a zoneConfig and a list of records - without any template values. Or you can use a template.

To use a template, you have to at least set the templateId property of the zoneConfig’s template values property. That will cause all record templates attached to the template to be converted into DNS records. Thus enabling you to create a full zone without providing a single record in the zoneCreate call.

Tying Zones to Templates

A zone may be tied to a template, determined by the tieToTemplate property of the zoneConfig’s template values.


Whenever a template is updated, the respective zones will also receive updates. This means:

A zone that is not tied to a template will not change when its respective template is updated.

If you change your mind, you do not need to recreate the zone. Instead, you can use zoneUntieFromTemplate to detach a zone from its template.

Placeholders

Placeholders are a crucial feature of the template system. There are five different placeholders you can use:


##NAME##, ##IPV4##, ##IPV6##, ##MX_IPV4##, and ##MX_IPV6##.

##NAME## will automatically be replaced with the name property of the zoneConfig. It may be used in the name and content properties of record templates. A record template with the type MX could, for example, have the name mail.##NAME##.

##IPV4##, ##IPV6##, ##MX_IPV4## and ##MX_IPV6## may only be used in the content property of record templates. Most commonly ##IPV4## is used for A records, ##IPV6## for AAAA records, and ##MX_IPV4## and ##MX_IPV6## to create target hostnames for MX records. However, usage is not restricted to a certain type.


Using these four placeholders requires replacement values. Not providing a replacement value for a placeholder when creating or recreating a zone from a template, will result in an error.

The replacement values have to be set in their respective properties in the template values object and they have to be valid according to their usage. For example, when your AAAA record template contains the ##IPV6## placeholder, the IPv6 replacement value has to be a valid IPv6 address.

As not all replacement values have to be set when you create a zone from a template, you may provide a template replacements object when recreating or updating a template.

This is necessary if you add a record template using a placeholder that has not been used before. Not all zones tied to the template might have a replacement value for the new placeholder. In that case, the replacement value from the template replacements object will be used as a default.

Property Type Required Description
id string see description ID of this template. Ignored in template create requests. Either ID or name is required in all other requests.
accountId string out-only ID of template managing account
name string req Freely chosen name. It has to be unique within the account.

The Template Replacements Object

TemplateReplacements Object

The template replacements object is used for recreating and updating templates.

Whenever a template is changed, all zones that are tied to the template are changed as well. If, for example, you add a new record template that contains a placeholder that has not been used in the template before, the zones tied to the template might not have a replacement value for the placeholder.

In that case the replacement value provided with the Template Replacements Object will be used as a default.

Property Type Required Description
ipv4Replacement string opt
ipv6Replacement string opt
mailIpv4Replacement string opt
mailIpv6Replacement string opt

The Record Template Object

RecordTemplate Object

Record templates are part of a template.

When you create a zone with a template, each of its RecordTemplates will be converted into a record. Updating a template and adding RecordTemplates will cause converted records to be added to all zones that are tied to the template.

Cf. template object for more details.

Property Type Required Description
id string cf. description RecordTemplate ID. Ignored in RecordTemplate create requests. Either id or templateId, name, type, and content are required in all other requests.
templateId string cf. description ID of template, the RecordTemplate is connected to. Required in non-create requests, if no id is provided.
name string cf. description Name for records created from RecordTemplate. It may contain the ##NAME## placeholder which will be replaced with zone name of zone created from template.
Example: mail.##NAME## may result in mail.example.com
type string cf. description Type for records created from RecordTemplate. Valid types are A, AAAA, MX, NS, CNAME, PTR, SRV
content string cf. description Content for records created from RecordTemplate. If the type is A, the ##IPV4## or ##MX_IPV4## placeholder may be used instead of a specific IPv4. If the type is AAAA, the ##IPV6## or ##MX_IPV6## placeholder may be used instead of a specific IPv6.
ttl int opt TTL for records created from RecordTemplate. Minimum value: 60. Less will result in a warning and the TTL will be corrected to the minimum. Maximum value: 31556926 (one year). Exceeding the maximum or undercutting the minimum value will cause the request to be aborted and result in an error.
priority int opt Priority for the records created from this RecordTemplate. Only relevant if the type is MX or SRV. Must be positive.

Listing Templates

POST https://partner.http.net/api/dns/v1/jsonxml/templatesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "accountId",
        "value": "150101000000001"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "templateName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>accountId</field>
    <value>150101000000001</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>templateName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // template objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindTemplatesResult"
    },
    ...
}
<response>
  ...
  <response>
    <data>
        // template objects
    </data>
    <limit>10</limit>
    <page>1</page>
    <totalEntries>15</totalEntries>
    <totalPages>2</totalPages>
    <type>FindTemplatesResult</type>
  </response>
  ...
</request>
RequesttemplatesFind
Urlhttps://partner.http.net/api/dns/v1/jsonxml/templatesFind
Processingsynchronous
ResponseFindTemplatesResult

Listing templates uses the generic filtering and sorting API with the method templatesFind. The response will contain a list of template objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of the account managing template
TemplateId Template object ID
TemplateName Name of the template

Listing Record Templates

POST https://partner.http.net/api/dns/v1/jsonxml/recordTemplatesFind
{
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "templateId",
        "value": "15010100000010"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "recordTemplateName",
        "order": "asc"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <filter>
    <field>templateId</field>
    <value>15010100000010</value>
  </filter>
  <limit>10</limit>
  <page>1</page>
  <sort>
    <field>recordTemplateName</field>
    <order>asc</order>
  </sort>
</request>
Response
{
    ...
    "response": {
        "data": [
            // record template objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindRecordTemplatesResult"
    },
    ...
}
<response>
  ...
  <response>
    <data>
        // record template objects
    </data>
    <limit>10</limit>
    <page>1</page>
    <totalEntries>15</totalEntries>
    <totalPages>2</totalPages>
    <type>FindRecordTemplatesResult</type>
  </response>
  ...
</request>
RequestrecordTemplatesFind
Urlhttps://partner.http.net/api/dns/v1/jsonxml/recordTemplatesFind
Processingsynchronous
ResponseFindRecordTemplatesResult

Listing template records uses the generic filtering and sorting API with the method recordTemplatesFind. The response will contain a list of template record objects.

The following fields are available for filtering and sorting:

Field Description
TemplateId ID of template object to which template record belongs
RecordTemplateId ID of template record object
RecordTemplateName Name of template record
RecordTemplateType Type of template record
RecordTemplateContent Content of template record
RecordTemplateTtl Time until template record is live (in seconds)
RecordTemplatePriority Priority of the template record (integer)

Creating Templates

POST https://partner.http.net/api/dns/v1/jsonxml/templateCreate
{
    "authToken": "$$YOUR API KEY$$",
    "dnsTemplate": {
        "name": "example template"
    },
    "recordTemplates": [
        {
            "name": "##DOMAIN##",
            "type": "A",
            "content": "##IPV4##",
            "ttl": 10000
        },
        {
            "name": "mail.##DOMAIN##",
            "type": "AAAA",
            "content": "##MX_IPV6##",
            "ttl": 10000,
            "priority": 10
        }
    ]
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <dnsTemplate>
    <name>example template</name>
  </dnsTemplate>
  <recordTemplates>
    <item>
      <content>##IPV4##</content>
      <name>##DOMAIN##</name>
      <ttl>10000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>##MX_IPV6##</content>
      <name>mail.##DOMAIN##</name>
      <priority>10</priority>
      <ttl>10000</ttl>
      <type>AAAA</type>
    </item>
  </recordTemplates>
</request>
Response
{
    ...
    "response": {
        "id": "150101000000010",
        "accountId": "150101000000001",
        "name": "example template"
    },
    ...
}
<response>
  ...
  <response>
    <accountId>150101000000001</accountId>
    <id>150101000000010</id>
    <name>example template</name>
  </response>
  ...
</request>
RequesttemplateCreate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/templateCreate
Processingsynchronous
ResponseTemplate
Parameter Type Required Description
dnsTemplate Template req Template to be created
recordTemplates list<RecordTemplate> req Record templates to be created and associated with template

Creates a new template. Please cf. the template object for more details on how to use templates.

Recreating Templates

POST https://partner.http.net/api/dns/v1/jsonxml/templateRecreate
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "dnsTemplate": {
        "name": "example template"
    },
    "recordTemplates": [
        {
            "name": "##DOMAIN##",
            "type": "A",
            "content": "##IPV4##",
            "ttl": 10000
        },
        {
            "name": "mail.##DOMAIN##",
            "type": "AAAA",
            "content": "##MX_IPV6##",
            "ttl": 10000,
            "priority": 10
        }
    ],
    "replacements": {
        "ipv4Replacement": "123.1.2.3",
        "ipv6Replacement": "2001:db8::2",
        "mailIpv4Replacement": "123.1.2.4",
        "mailIpv6Replacement": "2001:db8::1"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <clientTransactionId />
  <dnsTemplate>
    <name>example template</name>
  </dnsTemplate>
  <recordTemplates>
    <item>
      <content>##IPV4##</content>
      <name>##DOMAIN##</name>
      <ttl>10000</ttl>
      <type>A</type>
    </item>
    <item>
      <content>##MX_IPV6##</content>
      <name>mail.##DOMAIN##</name>
      <priority>10</priority>
      <ttl>10000</ttl>
      <type>AAAA</type>
    </item>
  </recordTemplates>
  <replacements>
    <ipv4Replacement>123.1.2.3</ipv4Replacement>
    <ipv6Replacement>2001:db8::2</ipv6Replacement>
    <mailIpv4Replacement>123.1.2.4</mailIpv4Replacement>
    <mailIpv6Replacement>2001:db8::1</mailIpv6Replacement>
  </replacements>
</request>
Response
{
    ...
    "response": {
        "id": "15010100000010",
        "accountId": "150101000000001",
        "name": "example template"
    },
    ...
}
<response>
  ...
  <response>
    <accountId>150101000000001</accountId>
    <id>15010100000010</id>
    <name>example template</name>
  </response>
  ...
</request>
RequesttemplateRecreate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/templateRecreate
Processingasynchronous
ResponseTemplate
Parameter Type Required Description
dnsTemplate Template req Template to be recreated
recordTemplates list<RecordTemplate> req Record templates to be recreated and connected with template
replacements TemplateReplacements opt Replacement values

Recreates an existing template. An error will be returned if the template does not exist.

Updating Templates

POST https://partner.http.net/api/dns/v1/jsonxml/templateUpdate
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "dnsTemplate": {
        "name": "example template"
    },
    "recordTemplatesToAdd": [
        {
            "name": "##DOMAIN##",
            "type": "AAAA",
            "content": "##IPV6##",
            "ttl": 3600
        }
    ],
    "recordTemplatesToDelete": [
        {
            "name": "mail.##DOMAIN##",
            "type": "AAAA",
            "content": "##MX_IPV6##"
        }
    ],
    "replacements": {
        "ipv4Replacement": "123.1.2.3",
        "ipv6Replacement": "2001:db8::2",
        "mailIpv4Replacement": "123.1.2.4",
        "mailIpv6Replacement": "2001:db8::1"
    }
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <clientTransactionId />
  <dnsTemplate>
    <name>example template</name>
  </dnsTemplate>
  <recordTemplatesToAdd>
    <item>
      <content>##IPV6##</content>
      <name>##DOMAIN##</name>
      <ttl>3600</ttl>
      <type>AAAA</type>
    </item>
  </recordTemplatesToAdd>
  <recordTemplatesToDelete>
    <item>
      <content>##MX_IPV6##</content>
      <name>mail.##DOMAIN##</name>
      <type>AAAA</type>
    </item>
  </recordTemplatesToDelete>
  <replacements>
    <ipv4Replacement>123.1.2.3</ipv4Replacement>
    <ipv6Replacement>2001:db8::2</ipv6Replacement>
    <mailIpv4Replacement>123.1.2.4</mailIpv4Replacement>
    <mailIpv6Replacement>2001:db8::1</mailIpv6Replacement>
  </replacements>
</request>
Response
{
    ...
    "response": {
        "id": "15010100000010",
        "accountId": "150101000000001",
        "name": "example template"
    },
    ...
}
<response>
  ...
  <response>
    <accountId>150101000000001</accountId>
    <id>15010100000010</id>
    <name>example template</name>
  </response>
  ...
</request>
RequesttemplateUpdate
Urlhttps://partner.http.net/api/dns/v1/jsonxml/templateUpdate
Processingasynchronous
ResponseTemplate
Parameter Type Required Description
dnsTemplate Template req Template to be updated
recordTemplatesToAdd list<RecordTemplate> req Record templates to be added to template
recordTemplatesToDelete list<RecordTemplate> req Record templates to be removed from template
replacements TemplateReplacements opt New replacement values

Updates an existing template. If the template does not exist, an error will be returned.

Deleting Templates

POST https://partner.http.net/api/dns/v1/jsonxml/templateDelete
{
    "authToken": "$$YOUR API KEY$$",
    "clientTransactionId": "",
    "templateId": "15010100000010"
}
<request>
  <authToken>$$YOUR API KEY$$</authToken>
  <clientTransactionId />
  <templateId>15010100000010</templateId>
</request>
Response
{
    ...
    "status": "success",
    ...
}

RequesttemplateDelete
Urlhttps://partner.http.net/api/dns/v1/jsonxml/templateDelete
Processingsynchronous
Responseempty
Parameter Type Required Description
templateId string req ID of template to be deleted
templateName string opt Name of the template to be deleted

Deletes an existing template and all record templates connected to it. If both ID and Name are set, the template does not exist, or zones are tied to the template, an error will be returned.

Mailboxes

The email section of the API allows you to create and manage mailboxes.

Currently three types of mailboxes are available in the system: ImapMailbox, ExchangeMailbox and Forwarder. First section of the documentation describes the objects that represent each of these types of mailboxes in detail. How to create and manage existing mailboxes is explained in the following sections.

ImapMailbox

The ImapMailbox Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "status": "active",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "type": "ImapMailbox",
    "productCode": "email-imap-mailbox-12m",
    "forwarderTargets": [],
    "smtpForwarderTarget": "",
    "isAdmin": false,
    "password": null,
    "storageQuota": 1024,
    "storageQuotaUsed": 0,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
}
<Mailbox>
 <id>150101aaaaaaaaaa001</id>
 <accountId>15010100000001</accountId>
 <emailAddress>testmailbox@example.com</emailAddress>
 <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <status>active</status>
 <spamFilter>
  <bannedFilesChecks>false</bannedFilesChecks>
  <deleteSpam>false</deleteSpam>
  <headerChecks>false</headerChecks>
  <malwareChecks>false</malwareChecks>
  <modifySubjectOnSpam>true</modifySubjectOnSpam>
  <spamChecks>false</spamChecks>
  <spamLevel>low</spamLevel>
  <useGreylisting>true</useGreylisting>
 </spamFilter>
 <type>ImapMailbox</type>
 <productCode>email-imap-mailbox-12m</productCode>
 <forwarderTargets/>
 <smtpForwarderTarget></smtpForwarderTarget>
 <isAdmin>false</isAdmin>
 <password xsi:nil="true"/>
 <storageQuota>1024</storageQuota>
 <storageQuotaUsed>0</storageQuotaUsed>
 <paidUntil>2016-02-01T15:57:35Z</paidUntil>
 <renewOn>2016-01-31T15:57:35Z</renewOn>
 <deletionScheduledFor xsi:nil="true"/>
 <restorableUntil xsi:nil="true"/>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>
Property Type Required / Direction Description
type string fixed Type of the mailbox. For imap mailbox it must always be “ImapMailbox”.
productCode string fixed Contains the productCode of the mailbox and must be set at creation.
accountId string out-only ID of account that manages this mailbox. (field is never used in requests)
id string see description ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress string required Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode string out-only Email address of the mailbox in Unicode/international format.
domainName string out-only Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode string out-only Domain name of the mailbox in Unicode/international format.
status string out-only Status of the mailbox.
spamFilter SpamFilter optional Spam settings of the mailbox.
forwarderTargets list required List of email addresses mails are forwarded to in addition to delivery to this imap mailbox.
isAdmin bool optional Indicates whether the mailbox has admin rights. Mailboxes with admin rights can create and manage other mailboxes in the same domain.
password string see description Required for mailboxCreate. Optional for mailboxUpdate, if set it is used as the new password for this mailbox. Always missing in api responses.
storageQuota int required Mailbox storage capacity in MB.
storageQuotaUsed int out-only Currently used storage of the mailbox in MB.
deletionScheduledFor datetime out-only Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil datetime out-only Date and Time before which the mailbox can be restored.
paidUntil datetime out-only Date that the mailbox is paid for.
renewOn datetime out-only Time of the next automatic debit of accounting period. This point of time is always before the paidUntil time. renewOn time calculation: subtract the notice period from paidUntil time.
addDate datetime out-only Date and time the mailbox was created in the system.
lastChangeDate datetime out-only Date and time of last mailbox modification

.

Creating ImapMailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxCreate
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "ImapMailbox",
        "productCode": "email-imap-mailbox-12m",
        "emailAddress": "testmailbox@example.com",
        "storageQuota": 1024,
        "password": "!Secret23",
        "isAdmin": false
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>ImapMailbox</type>
  <productCode>email-imap-mailbox-12m</productCode>
  <emailAddress>testmailbox@example.com</emailAddress>
  <password>!Secret23</password>
  <storageQuota>1024</storageQuota>
  <isAdmin>false</isAdmin>
 </mailbox>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "ImapMailbox",
    "productCode": "email-imap-mailbox-12m",
    "forwarderTargets": [],
    "smtpForwarderTarget": "",
    "isAdmin": false,
    "password": null,
    "storageQuota": 1024,
    "storageQuotaUsed": 0,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>ImapMailbox</type>
   <productCode>email-imap-mailbox-12m</productCode>
   <forwarderTargets/>
   <smtpForwarderTarget></smtpForwarderTarget>
   <isAdmin>false</isAdmin>
   <password xsi:nil="true"/>
   <storageQuota>1024</storageQuota>
   <storageQuotaUsed>0</storageQuotaUsed>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxCreate
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxCreate
Processingasynchronous
ResponseImapMailbox object
Parameter Type Required Description
mailbox ImapMailbox object req Data for to be created imap mailbox

In order to create an imap mailbox, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create an imap mailbox the type parameter of the mailbox must be ImapMailbox and all required properties of the ImapMailbox object must be set.

ExchangeMailbox

The ExchangeMailbox Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "status": "active",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "type": "ExchangeMailbox",
    "productCode": "email-msexchange-mailbox-1m",
    "firstName": "John",
    "lastName": "Doe",
    "exchangeGUID": "exampleguid",
    "organizationId": "150101aaaaaaaaaa111",
    "password": null,
    "storageQuota": 5120,
    "storageQuotaUsed": 0,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
}
<Mailbox>
 <id>150101aaaaaaaaaa001</id>
 <accountId>15010100000001</accountId>
 <emailAddress>testmailbox@example.com</emailAddress>
 <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <status>active</status>
 <spamFilter>
  <bannedFilesChecks>false</bannedFilesChecks>
  <deleteSpam>false</deleteSpam>
  <headerChecks>false</headerChecks>
  <malwareChecks>false</malwareChecks>
  <modifySubjectOnSpam>true</modifySubjectOnSpam>
  <spamChecks>false</spamChecks>
  <spamLevel>low</spamLevel>
  <useGreylisting>true</useGreylisting>
 </spamFilter>
 <type>ExchangeMailbox</type>
 <productCode>email-msexchange-mailbox-1m</productCode>
 <firstName>John</firstName>
 <lastName>Doe</lastName>
 <exchangeGUID>exampleguid</exchangeGUID>
 <organizationId>150101aaaaaaaaaa111</organizationId>
 <password xsi:nil="true"/>
 <storageQuota>5120</storageQuota>
 <storageQuotaUsed>0</storageQuotaUsed>
 <paidUntil>2016-02-01T15:57:35Z</paidUntil>
 <renewOn>2016-01-31T15:57:35Z</renewOn>
 <deletionScheduledFor xsi:nil="true"/>
 <restorableUntil xsi:nil="true"/>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>
Property Type Required / Direction Description
type string fixed Type of the mailbox. For imap mailbox it must always be ExchangeMailbox.
productCode string fixed Contains the productCode of the mailbox and must be set at creation.
accountId string out-only ID of account that manages this mailbox. (field is never used in requests)
id string see description ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress string required Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode string out-only Email address of the mailbox in Unicode/international format.
domainName string out-only Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode string out-only Domain name of the mailbox in Unicode/international format.
status string out-only Status of the mailbox.
spamFilter SpamFilter optional Spam settings of the mailbox.
firstName string required First name of the owner of the exchange mailbox
lastName string required Last name of the owner of the exchange mailbox
exchangeGUID string out-only Globally Unique Identifier of the exchange mailbox
organizationId string read-only ID of the organization in the system where the exchange mailbox is assigned. Required for mailboxCreate. It is not possible to change the organization after the exchange mailbox is created, therefore this property is ignored in mailboxUpdate requests.
password string see description Required for mailboxCreate. Optional for mailboxUpdate, if set it is used as the new password for this mailbox. Always missing in api responses.
storageQuota int required Mailbox storage capacity in MB.
storageQuotaUsed int out-only Currently used storage of the mailbox in MB.
deletionScheduledFor datetime out-only Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil datetime out-only Date and Time before which the mailbox can be restored.
paidUntil datetime out-only Date that the mailbox is paid for.
renewOn datetime out-only Time of the next automatic debit of accounting period. This point of time is always before the paidUntil time. renewOn time calculation: subtract the notice period from paidUntil time.
addDate datetime out-only Date and time the mailbox was created in the system.
lastChangeDate datetime out-only Date and time of last mailbox modification

The Organization Object

{
    "id": "150101aaaaaaaaaa111",
    "accountId": "15010100000001",
    "comment": "",
    "name": "testorganization",
    "status": "active",
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
}
<Organization>
 <id>150101aaaaaaaaaa111</id>
 <accountId>15010100000001</accountId>
 <name>testorganization</name>
 <status>active</status>
 <comment></comment>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Organization>
Property Type Required / Direction Description
accountId string out-only ID of account that manages this organization. This field is never used in requests.
id string see description ID of this organization. Ignored in organizationCreate requests. This property is required in all other requests regarding organization management.
name string required Name of the organization.
comment string optional Comments to the organization.
status string out-only Status of the organization.
memberDomains list out-only List of domains included in the organization.
addDate datetime out-only Date and time the organization was created in the system.
lastChangeDate datetime out-only Last date and time the organization was modified.

Creating Organizations

POST https://partner.http.net/api/email/v1/jsonxml/organizationCreate
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "organization": {
        "name": "testorganization"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <organization>
  <name>testorganization</name>
 </organization>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa111",
    "accountId": "15010100000001",
    "comment": "",
    "name": "testorganization",
    "status": "creating",
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa111</id>
   <accountId>15010100000001</accountId>
   <name>testorganization</name>
   <status>creating</status>
   <comment></comment>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestorganizationCreate
Urlhttps://partner.http.net/api/email/v1/jsonxml/organizationCreate
Processingasynchronous
ResponseOrganization object
Parameter Type Required Description
organization Organization object req Data for to be created organization

In order to create an exchange mailbox, you have to create an organization first and after that assign the new exchange mailbox to this organization. On order to create an organization you need to send a organizationCreate request. This request takes one parameter organization which contains all required information of the organization to be created.

Creating ExchangeMailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxCreate
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "ExchangeMailbox",
        "productCode": "email-msexchange-mailbox-1m",
        "emailAddress": "testmailbox@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "storageQuota": 5120,
        "password": "!Secret23",
        "organizationId": "150101aaaaaaaaaa111"
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>ExchangeMailbox</type>
  <productCode>email-msexchange-mailbox-1m</productCode>
  <emailAddress>testmailbox@example.com</emailAddress>
  <firstName>John</firstName>
  <lastName>Doe</lastName>
  <password>!Secret23</password>
  <storageQuota>5120</storageQuota>
  <organizationId>150101aaaaaaaaaa111</organizationId>
 </mailbox>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "ExchangeMailbox",
    "productCode": "email-msexchange-mailbox-1m",
    "firstName": "John",
    "lastName": "Doe",
    "exchangeGUID": "",
    "organizationId": "150101aaaaaaaaaa111",
    "password": null,
    "storageQuota": 5120,
    "storageQuotaUsed": 0,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>ExchangeMailbox</type>
   <productCode>email-msexchange-mailbox-1m</productCode>
   <firstName>John</firstName>
   <lastName>Doe</lastName>
   <exchangeGUID></exchangeGUID>
   <organizationId>150101aaaaaaaaaa111</organizationId>
   <password xsi:nil="true"/>
   <storageQuota>5120</storageQuota>
   <storageQuotaUsed>0</storageQuotaUsed>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxCreate
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxCreate
Processingasynchronous
ResponseExchangeMailbox object
Parameter Type Required Description
mailbox ExchangeMailbox object req Data for to be created exchange mailbox

In order to create an exchange mailbox, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create an exchange mailbox the type parameter of the mailbox must be ExchangeMailbox and all required properties of the ExchangeMailbox object must be set.

Forwarder

The Forwarder Object

{
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "status": "active",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "type": "Forwarder",
    "forwarderType": "externalForwarder",
    "productCode": "email-forwarder-external-12m",
    "forwarderTargets": [
        "internal_target@example.com",
        "external_target@testdomain.com"
    ],
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
}
<Mailbox>
 <id>150101aaaaaaaaaa001</id>
 <accountId>15010100000001</accountId>
 <emailAddress>testmailbox@example.com</emailAddress>
 <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <status>active</status>
 <spamFilter>
  <bannedFilesChecks>false</bannedFilesChecks>
  <deleteSpam>false</deleteSpam>
  <headerChecks>false</headerChecks>
  <malwareChecks>false</malwareChecks>
  <modifySubjectOnSpam>true</modifySubjectOnSpam>
  <spamChecks>false</spamChecks>
  <spamLevel>low</spamLevel>
  <useGreylisting>true</useGreylisting>
 </spamFilter>
 <type>Forwarder</type>
 <productCode>email-forwarder-external-12m</productCode>
 <forwarderType>externalForwarder</forwarderType>
 <forwarderTargets>
  <item>internal_target@example.com</item>
  <item>external_target@testdomain.com</item>
 </forwarderTargets>

 <paidUntil>2016-02-01T15:57:35Z</paidUntil>
 <renewOn>2016-01-31T15:57:35Z</renewOn>
 <deletionScheduledFor xsi:nil="true"/>
 <restorableUntil xsi:nil="true"/>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</Mailbox>
Property Type Required / Direction Description
type string fixed Type of the mailbox. For imap mailbox it must always be “Forwarder”.
productCode string fixed Contains the productCode of the mailbox and must be set at creation.
accountId string out-only ID of account that manages this mailbox. (field is never used in requests)
id string see description ID of this mailbox. Ignored in mailboxCreate requests. This property is required in all other requests regarding mailbox management.
emailAddress string required Email address of the mailbox in ASCII/ACE format.
emailAddressUnicode string out-only Email address of the mailbox in Unicode/international format.
domainName string out-only Domain name of the mailbox in ASCII/ACE format.
domainNameUnicode string out-only Domain name of the mailbox in Unicode/international format.
status string out-only Status of the mailbox.
spamFilter SpamFilter optional Spam settings of the mailbox.
forwarderType string out-only Type of the forwarder. The type of the forwarder can be either internalForwarder or externalForwarder. If all email addresses in the forwarderTargets list are in the same domain as the forwarder then the forwarderType will be internalForwarder. Otherwise it will be externalForwarder.
forwarderTargets list required List of email addresses mails are forwarded to.
deletionScheduledFor datetime out-only Date and time the mailbox is scheduled for deletion. Is empty if mailbox is not scheduled for removal.
restorableUntil datetime out-only Date and Time before which the mailbox can be restored.
paidUntil datetime out-only Date that the mailbox is paid for.
renewOn datetime out-only Time of the next automatic debit of accounting period. This point of time is always before the paidUntil time. renewOn time calculation: subtract the notice period from paidUntil time.
addDate datetime out-only Date and time the mailbox was created in the system.
lastChangeDate datetime out-only Date and time of last mailbox modification

Creating Forwarders

POST https://partner.http.net/api/email/v1/jsonxml/mailboxCreate
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "type": "Forwarder",
        "productCode": "email-forwarder-external-12m",
        "emailAddress": "testmailbox@example.com",
        "forwarderTargets": [
            "internal_target@example.com",
            "external_target@testdomain.com"
        ]
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <type>Forwarder</type>
  <productCode>email-forwarder-external-12m</productCode>
  <emailAddress>testmailbox@example.com</emailAddress>
  <forwarderTargets>
   <item>internal_target@example.com</item>
   <item>external_target@testdomain.com</item>
  </forwarderTargets>
 </mailbox>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "creating",
    "type": "Forwarder",
    "productCode": "email-forwarder-external-12m",
    "forwarderType": "externalForwarder",
    "forwarderTargets": [
        "internal_target@example.com",
        "external_target@testdomain.com"
    ],
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>creating</status>
   <type>Forwarder</type>
   <productCode>email-forwarder-external-12m</productCode>
   <forwarderType>externalForwarder</forwarderType>
   <forwarderTargets>
    <item>internal_target@example.com</item>
    <item>external_target@testdomain.com</item>
   </forwarderTargets>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxCreate
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxCreate
Processingasynchronous
ResponseForwarder object
Parameter Type Required Description
mailbox Forwarder object req Data for to be created forwarder

In order to create a forwarder, you need to send a mailboxCreate request. This request takes one parameter mailbox which contains all required information of the mailbox to be created. Please note that in order to create an forwarder mailbox the type parameter of the mailbox must be Forwarder and all required properties of the Forwarder object must be set.

Spam filtering settings

The SpamFilter Object

{
    "bannedFilesChecks": false,
    "deleteSpam": false,
    "headerChecks": false,
    "malwareChecks": false,
    "modifySubjectOnSpam": true,
    "spamChecks": false,
    "spamLevel": "low",
    "useGreylisting": true
}
<spamFilter>
 <bannedFilesChecks>false</bannedFilesChecks>
 <deleteSpam>false</deleteSpam>
 <headerChecks>false</headerChecks>
 <malwareChecks>false</malwareChecks>
 <modifySubjectOnSpam>true</modifySubjectOnSpam>
 <spamChecks>false</spamChecks>
 <spamLevel>low</spamLevel>
 <useGreylisting>true</useGreylisting>
</spamFilter>
Property Type Required / Direction Description
bannedFilesChecks bool optional Will reject mails with potentially dangerous attachments (like .exe files).
deleteSpam bool optional Reject spam mails
headerChecks bool optional The email headers will be checked for unusual patterns.
malwareChecks bool optional This option enables the scanning of content and attachments of emails for malware and viruses.
modifySubjectOnSpam bool optional Will modify the subject to mark a recognized spam email as such.
spamChecks bool optional The content of emails will be compared against a spam database and will mark the Subject if required (see modifySubjectOnSpam).
spamLevel string optional The levels indicate how many spam factors are taken into account when an email arrives. Valid values: low, medium. high
useGreylisting bool optional Greylisting will delay the acceptance of emails, allowing significantly better recognition of spam.

Updating Mailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxUpdate
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailbox": {
        "id": "150101aaaaaaaaaa001",
        "type": "ImapMailbox",
        "emailAddress": "testmailbox@example.com",
        "storageQuota": 1024,
        "password": "!Secret23",
        "isAdmin": false
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailbox>
  <id>150101aaaaaaaaaa001</id>
  <emailAddress>testmailbox@example.com</emailAddress>
  <password>!Secret23</password>
  <storageQuota>1024</storageQuota>
  <type>ImapMailbox</type>
  <isAdmin>false</isAdmin>
 </mailbox>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    "status": "active",
    "type": "ImapMailbox",
    "forwarderTargets": [],
    "smtpForwarderTarget": "",
    "isAdmin": false,
    "password": null,
    "storageQuota": 1024,
    "storageQuotaUsed": 0,
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   <status>active</status>
   <type>ImapMailbox</type>
   <forwarderTargets/>
   <smtpForwarderTarget></smtpForwarderTarget>
   <isAdmin>false</isAdmin>
   <password xsi:nil="true"/>
   <storageQuota>1024</storageQuota>
   <storageQuotaUsed>0</storageQuotaUsed>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxUpdate
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxUpdate
Processingasynchronous
ResponseImapMailbox, ExchangeMailbox or Forwarder object
Parameter Type Required Description
mailbox ImapMailbox, ExchangeMailbox or Forwarder object req Complete mailbox object of the same type as the mailbox to update.

The mailbox that you want to update is identified by it’s id. All fields not marked out-only are set to the values in the mailbox argument. Optional fields that are not specified in this call are reset to their default values.

Listing Mailboxes

POST https://partner.http.net/api/email/v1/jsonxml/Find
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "MailboxEmailAddress",
        "value": "testmailbox@example.com"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "MailboxEmailAddress",
        "order": "asc"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>MailboxEmailAddress</field>
  <value>testmailbox@example.com</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>MailboxEmailAddress</field>
  <order>asc</order>
 </sort>
</request>

Response
{
    ...
    "response": {
        "data": [
            // Mailbox objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindMailboxesResult"
    },
    ...
}

<response>
 <response>
  <data>
   ...
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindMailboxesResult</type>
 </response>
 ...
</response>

RequestmailboxesFind
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxesFind
Processingsynchronous
ResponseFindMailboxesResult

Listing mailboxes uses the generic filtering and sorting API with the method mailboxesFind. The response will contain a list of mailbox objects.

The following fields are available for filtering and sorting:

Field Description
AccountId ID of account managing the mailbox
MailboxId ID of mailbox
MailboxEmailAddress Email address of the mailbox
MailboxEmailAddressUnicode Email address of the mailbox in Unicode-Form
MailboxDomainName Domain name of the mailbox
MailboxDomainNameUnicode Domain name of the mailbox in Unicode-Form
MailboxType Type of the mailbox
MailboxStatus Status of the mailbox
MailboxStorageQuota Mailbox storage capacity
MailboxStorageQuotaUsed Currently used storage of the mailbox
MailboxDeletionScheduledFor Deletion date and time of the mailbox
MailboxRestorableUntil Date and Time until mailbox can be restored
MailboxPaidUntil Time that the mailbox is paid for
MailboxRenewOn Date and Time of next automatic renewal (and payment)
MailboxAddDate Date and time mailbox was created
MailboxLastChangeDate Date and time of last modification

Deleting Mailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxDelete
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001",
    "execDate": "2016-01-15T12:00:00Z"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
 <execDate>2016-01-15T12:00:00Z</execDate>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    //mailbox type specific properties
    "status": "active",    
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": "2016-01-15T12:00:00Z",
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   ...mailbox type specific properties
   <status>active</status>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor>2016-01-15T12:00:00Z</deletionScheduledFor>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxDelete
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxDelete
Processingasynchronous
ResponseMailbox object
Parameter Type Required Description
mailboxId string see description Id of the mailbox
emailAddress string see description Email address of the meilbox
execDate datetime optional Scheduled deletion date

This method deletes a mailbox. To delete a mailbox you must specify either the id of the mailbox or its email address, but not both.

A deleted mailbox can be restored within the restore period with the mailboxRestore API method. If the mailbox will not be restored within the restore period it will be removed from the system.

If you also specify an execDate, it will be scheduled for deletion on execDate. This will set the mailbox object’s and deletionDate. A scheduled deletion can be canceled with the mailboxDeletionCancel API method.

Canceling Deletion of Mailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxDeletionCancel
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    //mailbox type specific properties
    "status": "active",    
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": null,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   ...mailbox type specific properties
   <status>active</status>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil xsi:nil="true"/>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxDeletionCancel
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxDeletionCancel
Processingsynchronous
ResponseMailbox object
Parameter Type Required Description
mailboxId string see description Id of the mailbox
emailAddress string see description Email address of the mailbox

This method cancels a scheduled deletion for a mailbox. To cancel a deletion of a mailbox you must specify either the id of the mailbox or its email address, but not both.

Restoring Mailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxRestore
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
</request>
Response
{
  ...
  "response": {
    "id": "150101aaaaaaaaaa001",
    "accountId": "15010100000001",
    "emailAddress": "testmailbox@example.com",
    "emailAddressUnicode": "testmailbox@example.com",
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "spamFilter": {
      "bannedFilesChecks": false,
      "deleteSpam": false,
      "headerChecks": false,
      "malwareChecks": false,
      "modifySubjectOnSpam": true,
      "spamChecks": false,
      "spamLevel": "low",
      "useGreylisting": true
    },
    //mailbox type specific properties
    "status": "restorable",
    "paidUntil": "2016-02-01T15:57:35Z",
    "renewOn": "2016-01-31T15:57:35Z",
    "deletionScheduledFor": null,
    "restorableUntil": "2016-01-22T12:00:00Z",
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-15T12:00:00Z"
  }
}
<response>
 <response>
  <response>
   <id>150101aaaaaaaaaa001</id>
   <accountId>15010100000001</accountId>
   <emailAddress>testmailbox@example.com</emailAddress>
   <emailAddressUnicode>testmailbox@example.com</emailAddressUnicode>
   <domainName>example.com</domainName>
   <domainNameUnicode>example.com</domainNameUnicode>
   <spamFilter>
    <bannedFilesChecks>false</bannedFilesChecks>
    <deleteSpam>false</deleteSpam>
    <headerChecks>false</headerChecks>
    <malwareChecks>false</malwareChecks>
    <modifySubjectOnSpam>true</modifySubjectOnSpam>
    <spamChecks>false</spamChecks>
    <spamLevel>low</spamLevel>
    <useGreylisting>true</useGreylisting>
   </spamFilter>
   ...mailbox type specific properties
   <status>restorable</status>
   <paidUntil>2016-02-01T15:57:35Z</paidUntil>
   <renewOn>2016-01-31T15:57:35Z</renewOn>
   <deletionScheduledFor xsi:nil="true"/>
   <restorableUntil>2016-01-22T12:00:00Z</restorableUntil>
   <addDate>2016-01-01T15:57:35Z</addDate>
   <lastChangeDate>2016-01-15T12:00:00Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestmailboxRestore
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxRestore
Processingasynchronous
ResponseMailbox object
Parameter Type Required Description
mailboxId string see description Id of the mailbox
emailAddress string see description Email address of the mailbox

This method restores a previously deleted mailbox. After the mailbox is restored it can be used normally. To restore a mailbox you must specify either the id of the mailbox or its email address, but not both.

Purging Restorable Mailboxes

POST https://partner.http.net/api/email/v1/jsonxml/mailboxPurgeRestorable
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "mailboxId": "150101aaaaaaaaaa001"
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <mailboxId>150101aaaaaaaaaa001</mailboxId>
</request>
Response
{
  ...
  "status": "pending"
}
<response>
 <response>  
   <status>pending</status>
 ...
</response>
RequestmailboxPurgeRestorable
Urlhttps://partner.http.net/api/email/v1/jsonxml/mailboxPurgeRestorable
Processingasynchronous
Responsenone
Parameter Type Required Description
mailboxId string see description id of the mailbox
emailAddress string see description email address of the meilbox

This method deletes a restorable mailbox immediately from the system. You will not be able to restore it afterwards. To use this method you must specify either the id of the mailbox or its email address, but not both.

Checking Mailbox Authorization

RequestcheckEmailAddress
Urlhttps://partner.http.net/api/email/v1/jsonxml/checkEmailAddress
Processingsynchronous
Response
Parameter Type Required Description
emailAddress string req Email address of the mailbox

This method checks if an mailbox can be created and if dns authorizationes required (This happens when the domain is not in your account).

If status in the result object is emailAddressAvailable you can proceed to create the mailbox.

If status in the result object is verificationRequired you need to create a TXT DNS record in the domain with the value from the verificationCode field in the result object.

Domain Settings

Domain settings serve to display and limit the usage of mailboxes in a certain domain.

The DomainSettings Object

{
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "storageQuota": -1,
    "storageQuotaAllocated": 1024,
    "mailboxQuota": -1,
    "exchangeMailboxQuota": -1,
    "exchangeStorageQuotaAllocated": 0,
    "exchangeStorageQuota": -1,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-01T15:57:35Z"
}
<DomainSettings>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <storageQuota>-1</storageQuota>
 <storageQuotaAllocated>1024</storageQuotaAllocated>
 <mailboxQuota>-1</mailboxQuota>
 <exchangeMailboxQuota>-1</exchangeMailboxQuota>
 <exchangeStorageQuotaAllocated>0</exchangeStorageQuotaAllocated>
 <exchangeStorageQuota>-1</exchangeStorageQuota>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-01T15:57:35Z</lastChangeDate>
</DomainSettings>
Property Type Required / Direction Description
domainName string required Domain name in ASCII/ACE format.
domainNameUnicode string out-only Domain name in Unicode/international format.
storageQuota int optional Storage quota allowed to be used in this domain for imap mailboxes.
storageQuotaAllocated int out-only Currently used storage in this domain for imap mailboxes.
mailboxQuota int optional Number of imap mailboxes allowed to be created in this domain.
exchangeStorageQuota int optional Storage quota allowed to be used in this domain for exchange mailboxes.
exchangeStorageQuotaAllocated int out-only Currently used storage in this domain for exchange mailboxes.
exchangeMailboxQuota int optional Number of exchange mailboxes allowed to be created in this domain.
addDate datetime out-only Date and time the mailbox was created in the system.
lastChangeDate datetime out-only Last date and time the mailbox was modified.

Listing Domain Settings

POST https://partner.http.net/api/email/v1/jsonxml/Find
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "filter": {
        "field": "DomainName",
        "value": "example.com"
    },
    "limit": 10,
    "page": 1,
    "sort": {
        "field": "DomainName",
        "order": "asc"
    }
}

<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
 <filter>
  <field>DomainName</field>
  <value>example.com</value>
 </filter>
 <limit>10</limit>
 <page>1</page>
 <sort>
  <field>DomainName</field>
  <order>asc</order>
 </sort>
</request>

Response
{
    ...
    "response": {
        "data": [
            // DomainSettings objects
        ],
        "limit": 10,
        "page": 1,
        "totalEntries": 15,
        "totalPages": 2,
        "type": "FindDomainSettingsResult"
    },
    ...
}

<response>
 <response>
  <data>
   ...DomainSettings objects
  </data>
  <limit>10</limit>
  <page>1</page>
  <totalEntries>15</totalEntries>
  <totalPages>2</totalPages>
  <type>FindDomainSettingsResult</type>
 </response>
 ...
</response>

RequestdomainSettingsFind
Urlhttps://partner.http.net/api/email/v1/jsonxml/domainSettingsFind
Processingsynchronous
ResponseFindDomainSettingsResult

Listing domain settings uses the generic filtering and sorting API with the method domainSettingsFind. The response will contain a list of DomainSettings objects.

The following fields are available for filtering and sorting:

Field Description
DomainName Domain name
MailboxId ID of mailbox
MailboxEmailAddress Email address of the mailbox
MailboxEmailAddressUnicode Email address of the mailbox in Unicode-Form
MailboxDomainName Domain name of the mailbox
MailboxDomainNameUnicode Domain name of the mailbox in Unicode-Form

Updating DomainSettings

It is possible to limit mailboxes number or storage usage for certain domains using the DomainSettings object and domainSettingsUpdate API method.

POST https://partner.http.net/api/email/v1/jsonxml/domainSettingsUpdate
{
    ...
    "authToken": "$$YOUR API KEY$$",
    "domainSettings": {
        "domainName": "example.com",
        "storageQuota": 10240,
        "mailboxQuota": 10,
        "exchangeMailboxQuota": -1,
        "exchangeStorageQuota": -1
    }
}
<request>
 ...
 <authToken>$$YOUR API KEY$$</authToken>
<domainSettings>
 <domainName>example.com</domainName>
 <storageQuota>10240</storageQuota>
 <mailboxQuota>10</mailboxQuota>
 <exchangeMailboxQuota>-1</exchangeMailboxQuota>
 <exchangeStorageQuota>-1</exchangeStorageQuota>
</domainSettings>
</request>
Response
{
  ...
  "response": {
    "domainName": "example.com",
    "domainNameUnicode": "example.com",
    "storageQuota": 10240,
    "storageQuotaAllocated": 1024,
    "mailboxQuota": 10,
    "exchangeMailboxQuota": -1,
    "exchangeStorageQuotaAllocated": 0,
    "exchangeStorageQuota": -1,
    "addDate": "2016-01-01T15:57:35Z",
    "lastChangeDate": "2016-01-15T12:00:00Z"
  }
}
<response>
 <response>
  <response>
 <domainName>example.com</domainName>
 <domainNameUnicode>example.com</domainNameUnicode>
 <storageQuota>10240</storageQuota>
 <storageQuotaAllocated>1024</storageQuotaAllocated>
 <mailboxQuota>10</mailboxQuota>
 <exchangeMailboxQuota>-1</exchangeMailboxQuota>
 <exchangeStorageQuotaAllocated>0</exchangeStorageQuotaAllocated>
 <exchangeStorageQuota>-1</exchangeStorageQuota>
 <addDate>2016-01-01T15:57:35Z</addDate>
 <lastChangeDate>2016-01-15T12:00:00Z</lastChangeDate>
  </response>
 </response>
 ...
</response>
RequestdomainSettingsUpdate
Urlhttps://partner.http.net/api/email/v1/jsonxml/domainSettingsUpdate
Processingsynchronous
ResponseDomainSettings object
Parameter Type Required Description
domainSettings DomainSettings object req Data for the domain settings to be updated