This document describes the functions that can be called through the Maildesk API.

Authentication ¶

To use the API, you should create an API Key first. This can be done in the Maildesk Interface. Multiple API-keys can be created in your tenant. Each API key can also be bound to an IP-address. This will further secure the connections to this API.

If you have an API-Key, you will need to send this key with each request in the Authorization-header to the API. This will authenticate your client and give you access to all the information inside the tenant it is assigned to.

Authorization: Bearer 5262d64b892e8d4341000001

Headers ¶

Format ¶

The API implements two Content Types ( json or xml ). The content will be evaluated based on two headers: Content-Type/Accept. The headers can be combined as you wish. It is possible to send a json-request and receive an xml-response.

• The ‘Content-Type’ header will be used to process your request.

• The ‘Accept’ header will be used to format the response.

The default is ‘application/json’. So if no ( or an invalid ) header is found, the json-format will be used. In the examples below only the JSON response will be shown, but you can always choose your request/response format.

Content-Type:   application/xml,application/json
Accept:         application/xml,application/json

Responses ¶

Response code ¶

The API will mostly return ‘200’. This is due to the fact that you can specify more than one action in a request. If the general format of the request is correct, but an object action fails, the result code will be ‘200 OK’. But you will need to check every result for an error.

You can get the following error codes:

• [401] The 401 error code will be used for a non-authenticated request. The most likely cause is no ( or an incorrect ) ‘Authentication’ Header.

• [400] The 400 error code will be send if the request is not formatted in the expected format ( e.g., XML send with the json ‘Content-Type’ Header ).

• [500] This will be used if an unkown error occures on the server. If you get this error, please contact us, so we can check the error-logs.

Limit ¶

The API will limit the maximum of operations to 100 in one request. If you pass more operations in one request, all requests above the limit will be dropped. There will be a message in the response to notify you of this drop.

Object Type ¶

The object type will inform you about the type of response provided by the API. In an JSON response, this will be provided in the ‘object_type’ parameter. In a JSON responses, this will be provided in the ‘object_type’ parameter. In an XML reponse this will be the tagname.

{
    "results": [
        {
            "object_type": "contact"
            ...
        },
        {
            "object_type": "response"
            ...
        }
    ]
}

{
  <results>
    <contact ref="00001">...</contact>
    <reponse message="..."/>
  </results>
}

Resources ¶

Contacts ¶

A contact in Maildesk contains the email address of the contact. The email address is always unique. It is not possible to create multiple contacts with the same email address.

Contacts can be referenced based on two values: GUID and REF. This will allow you to quickly find the contact you need. In each request for contacts one or both references can be used. If both are used, both parameters need to match to get a result ( AND operation ).

• GUID: This is an unique ID assigned by Maildesk to every contact.

• REF: This is a unique reference you can set when creating the contact ( e.g., the ID in your CRM ). This allows you to find contacts quickly, without saving the guid.

Tags ¶

A tag will allow you to segregate your contacts in sections. These can then be used to target your mailing. Tags must be referenced based on the tag name.

Content-Type: application/json

{
  "results": [
      {
          "object_type": "contact",
          "ref": "549884",
          "guid": "9d330ffc-5985-4033-affe-cde13aabe8b3",
          "mail_address": "info@example.org",
          "tags": [
              {
                  "value": "domain customer",
                  "manual": false
              },
              {
                  "value": "office 365 customer",
                  "manual": false
              }
          ],
          "fields": [
              {
                  "field": "name",
                  "value": "John Doe"
              },
          ]
      }
    ]
}

Content-Type: application/json

{
  "contacts": [
    {
      "ref": "0000002",
      "mail_address": "info@example.org",
      "tags": [
        {
          "tag": "nl"
        },
        {
          "tag": "webshop customer"
        }
      ],
      "fields": [
        {
          "field": "naam",
          "value": "John"
        }
      ]
    }
  ]
}

Content-Type: application/json

{
  "results": [
    {
      "object_type": "contact",
      "ref": "0000002",
      "mail_address": "info@example.org",
      "message": "successful_created"
    }
  ]
}

Content-Type: application/json

{
  "contacts": [
    {
      "ref": "0000002",
      "mail_address": "info@example.org",
      "tags": [
        {
          "tag": "nl"
        },
        {
          "tag": "webshop customer"
        }
      ],
      "fields": [
        {
          "field": "naam",
          "value": "John"
        }
      ]
    }
  ]
}

Content-Type: application/json

{
  "results": [
    {
      "object_type": "contact",
      "ref": "0000002",
      "mail_address": "info@example.org",
      "message": "successful_updated"
    }
  ]
}

Content-Type: application/json

{
  "contacts": [
    {
      "ref": "00000001"
    },
    {
      "ref": "00000002"
    }
  ]
}

Content-Type: application/json

{
  "results": [
    {
      "object_type": "contact",
      "ref": "00000001",
      "message": "contact_not_found"
    },
    {
      "object_type": "contact",
      "ref": "00000002",
      "message": "contact_removed"
    }
  ]
}

Content-Type: application/json

{
  "results": [
    {
      "object_type": "tag",
      "tag": "webshop customer",
      "computed": false
    }
  ]
}

Content-Type: application/json

Content-Type: application/json

{
  "results": [
    {
      "object_type": "response",
      "tag": "webshop customer",
      "message": "object_created"
    },
    {
      "object_type": "response",
      "tag": "en",
      "message": "object_created"
    }
  ]
}

Content-Type: application/json

{
  "tags": [
    {
      "tag": "webshop customer"
    },
    {
      "tag": "nl"
    }
  ]
}

Content-Type: application/json

{
  "results": [
    {
      "object_type": "tag",
      "tag": "webshop customer",
      "message": "object_removed"
    },
    {
      "object_type": "tag",
      "tag": "en",
      "message": "object_removed"
    }
  ]
}

Content-Type: application/json

{
"results": [
    {
        "object_type": "field",
        "field": "first name",
    }
]
}

Content-Type: application/json

Content-Type: application/json

{
  "results": [
    {
      "object_type": "response",
      "tag": "first name",
      "message": "object_created"
    },
    {
      "object_type": "response",
      "tag": "last name",
      "message": "object_created"
    }
  ]
}

Content-Type: application/json

{
  "fields": [
    {
      "field": "first name"
    },
    {
      "field": "last name"
    }
  ]
}

Content-Type: application/json

{
  "results": [
    {
      "object_type": "field",
      "tag": "first name",
      "message": "object_removed"
    },
    {
      "object_type": "field",
      "tag": "last name",
      "message": "object_removed"
    }
  ]
}