dmarcian API (1.0.0)

Welcome to the dmarcian REST API documentation!

This documentation will help you integrate the dmarcian services into your software so you are not required to use our user interface. We have put a lot of effort into making the endpoints as self descriptive as possible but even if you have any issues - head to the corresponding section in the reference below.

We have built the API on top of HTTP following REST best practices. The endpoints receive JSON in their request body and return JSON as a response with the proper status code.

Most of our API endpoints are not publicly available so you must authenticate in order to use them. To do so you need to acquire an API token first. Navigate to the Manage Settings page and generate one there. You can always regenerate it but keep in mind that this will revoke your old token and it won't be accepted anymore.

Once you have a token you need to provide it as an HTTP header on each request you make:

Authorization: Token {your-api-token}

The API is constantly evolving to match the new features we add to the dmarcian platform. In order to ensure backward compatibility and not break clients we have versioned the API. Each endpoint contains a parameter in the URL that specifies the requested version and looks like this:

/api/v{version-number}/domains/

Endpoint calls can result in one of the following HTTP Status Codes:

* Have in mind that properties specified in the request body that are not supported will be IGNORED.

HATEOAS (Hypermedia as the Engine of Application State) is a very cool idea. In essence - endpoint responses provide navigation information by including hypermedia links to the available actions / resources. The main benefit is that clients do not have to be familiar how endpoint URLs are built and do not need to hardcode them inside their API integration.

We have embraced this idea but we have deviated from the specification a bit to have a simpler response structure. We have also added an extra layer on top - permissions. Responses may contain a _links property that lists all available actions and a _permissions property that specifies which of the actions are permitted to the current user.

The API provides a root endpoint that lists all main resources and links to explore them.

For the latest API version call:

https://<region>.dmarcian.com/api/

For a specific API version call:

https://<region>.dmarcian.com/api/v{version-number}/

Example response:

{
    "domains": "https://<region>.dmarcian.com/api/v1/domains/",
    "domain_groups": "https://<region>.dmarcian.com/api/v1/domain-groups/",
    "issues": "https://<region>.dmarcian.com/api/v1/issues/",
    "tasks": "https://<region>.dmarcian.com/api/v1/tasks/"
}

All list API endpoints support pagination and share an identical response format (check a specific endpoint reference for a detailed response schema). The _links property contains URLs for navigation - first page, last page, next page, etc. and the _permissions property specifies what is permitted - e.g. only list or also create.

Example response:

{
    "_links": {
        "first": "https://<region>.dmarcian.com/api/v1/domains/",
        "last": "https://<region>.dmarcian.com/api/v1/domains/?page=5",
        "next": "https://<region>.dmarcian.com/api/v1/domains/?page=2",
        "previous": null
    },
    "_permissions": [
        "list"
    ],
    "count": 24,
    "pages": 5,
    "current_page": 1,
    "per_page": 5,
    "results": []
}

Object API endpoints operate on a specific resource with a unique identifier. The _links property works the same way as described above with one specific difference - the self key inside is used for multiple actions - retrieve, update, partial_update and destroy.

Example response:

{
    "_links": {
        "self": "https://<region>.dmarcian.com/api/v1/domains/17/",
        "refresh": "https://<region>.dmarcian.com/api/v1/domains/17/refresh/",
        "subdomains": "https://<region>.dmarcian.com/api/v1/domains/?parent_id=17&treat_as_top_level=False"
    },
    "_permissions": [
        "retrieve",
        "refresh",
        "update",
        "partial_update",
        "destroy"
    ],
    "id": 17,
    ...
}

API returns date fields as a string representing the UTC date and time in ISO 8601 format, YYYY-MM-DDTHH:MM:SS.mmmmmm or, if microsecond is 0, YYYY-MM-DDTHH:MM:SS.

In example below Z is the zone designator for the zero UTC offset.

{
  "created": "2017-09-11T10:18:50.875874Z"
}

API accepts date time in ISO 8601 format with given UTC offset(Z for zero or ±HH:MM):

{
  "begin": "2017-09-11T10:18:50+03:00",
  "end": "2017-09-11T10:18:50+03:00"
}

After getting familiar with the basics it's time to get our hands dirty and actually do something with the API. In this How To section we are going to describe some common scenarios - check the reference for more advanced cases.

dmarcian does not provide any SDKs currently but communication with the API can be achieved in any programming language since all endpoints are HTTP based. We will use curl in our examples for simplicity.

The first step after creating an account at dmarcian is to add a domain so we are going to describe how can this be achieved via the API.

1. Get Token

Check the Authentication section for details how to obtain an API token - we will need it for calling the API.

2. List Domain Groups

All domains live under a certain domain group (either the default one which you will automatically have after registration or a group you have created). In order to create a domain we need to find a group to add it to first:

curl -G https://<region>.dmarcian.com/api/v1/domain-groups/ -H 'Authorization: Token {your-api-token}'

You will get a paginated list of all available groups. Just choose the one you want to add a domain to (look inside the results property) and copy the add_domain URL under _links - we will use it in the next step.

3. Add the Domain

After we've chosen a group we can actually add the domain:

curl -d '{"domains":["example.com"]}' https://<region>.dmarcian.com/api/v1/domain-groups/{chosen-group-id}/add-domains/ -H 'Authorization: Token {your-api-token}' -H 'Content-Type: application/json'

The response will contain URLs to the newly created domains:

{
    "added": ["https://<region>.dmarcian.com/api/v1/domains/{created-domain-id}/"]
}

4. List Domains

And voila - you have added your first domain via the API. Now let's verify that the domain is listed under the group. Copy the domains property under _links from the group you chose in step 2 and list the domains:

curl -G 'https://<region>.dmarcian.com/api/v1/domains/?treat_as_top_level=True&group_id={chosen-group-id}' -H 'Authorization: Token {your-api-token}'

You should see the new domain in the results property of the paginated response.

The API reference allows you to dive into each endpoint and check how example requests and response look like, what filters are supported and what is the meaning of each property.

User endpoints allow management of users that belong to your organization. In order to use these endpoints you need admin access.

Domain Group ACL allow you to control the level of access to domains within a particular group. There are three available options: no access, read-only and write access.In order to use these endpoints you need admin access.

Domain group is a list of domains. By definition the DEFAULT group contains all domains. It is possible to configure the DEFAULT group to hide domains added to other groups. For other than the DEFAULT group you can configure the group for parked domains (not expected to send email) only. Other options are batch add/delete and move domains from one group to another.

Domains are the main entity in your Domain Catalog. When you add your domains to dmarcian we start monitoring numerous things - the state of your SPF, DKIM and DMARC records, the email volumes sent from those domains and what is their compliance level (if they have DMARC records with reporting sent to dmarcian). This way you will get an overview of your domains, identifying which ones send email and in what volumes.