Skip to content

Instantly share code, notes, and snippets.

@cnicodeme

cnicodeme/api.md

Last active Oct 7, 2019
Embed
What would you like to do?
ImprovMX documentation

ImprovMX API

This is the documentation of our API endpoint at ImprovMX.com. This lets you list, create, edit and remove domain and email aliases that you can forward to programatically.

For more information, visit ImprovMX.com

URL

The base url's ImprovMX api can be accessed at

https://api.improvmx.com/v2/

Authentication

Get your API Key by visiting the following link.

Authentication is done via the "Basic auth mechanism". Simply pass the string "api" as the username and your API key as the password, like the following:

Authorization: Basic api:{your_api_key}

(Note: You need to base64 encode the "api:{your_api_key}" part)

That's it, you are ready to communicate with our API.

Error codes

Here are the main error codes you will encounter:

Code Description
200 Succes This means the request was successfully made
400 Bad Request This means you passed a wrong or missing parameter
403 Forbidden The API key you provided is not valid or you are trying to access a protected resource
500 Server error This happens when we have a bug... Reach out to us and we'll fix it :)

When an error occurs, you will always receive a JSON response in the body, explaining in details what was the reason of the failure, which will help you understand and adapt your subsequent requests accordingly.

For instance, here's an example of a Bad Request response returned by the server:

{
    "errors": {
        "email": [
            "You cannot use your domain in your email."
        ]
    },
    "success": false
}

Account

GET /v2/account/

Get the details about your account*

GET /v2/account/

Returns a JSON object like the following:

{
    "email": "contact@your-company.tld",
    "company_name": "Your company name",
    "company_details": "Your address",
    "company_vat": "Some vat number",
    "card_brand": null,
    "country": "US",
    "created": 1542015888000,
    "last4": null,
    "plan_amount": null,
    "premium": false,
    "renew_date": null
}

GET /v2/account/api/

Retrieve your API Key details

GET /v2/account/api/

Returns a JSON object like the following:

{
    "token": "sk_352a0abd12074355b8612a50c5136d29",
    "created": 1553264776000, 
    "name": null, 
    "removed": null, 
}

Domains

GET /v2/domains/

Retrieve a list of all your domains

GET /v2/domains/

Returns a JSON object like the following:

{
    "domains": [
        {
            "active": true, 
            "domain": "google.com", 
            "added": 1559639697000, 
            "daily_quota": 500, 
            "aliases": [
                {
                    "forward": "sergey@gmail.com", 
                    "alias": "sergey", 
                    "id": 1
                },
                {
                    "forward": "larry@gmail.com", 
                    "alias": "larry", 
                    "id": 2
                }
            ]
        }, 
        {
            "active": true, 
            "domain": "facebook.com", 
            "added": 1559639727000, 
            "daily_quota": 500, 
            "aliases": [
                {
                    "forward": "mark@facebook-mail.com", 
                    "alias": "*", 
                    "id": 3
                }
            ]
        }, 
        {
            "active": false, 
            "domain": "piedpiper.com", 
            "added": 1559639733000, 
            "daily_quota": 500, 
            "aliases": [
                {
                    "forward": "richard.hendricks@gmail.com", 
                    "alias": "richard", 
                    "id": 4
                },
                {
                    "forward": "jared.dunn@gmail.com", 
                    "alias": "jared", 
                    "id": 5
                },
                {
                    "forward": "monica.hall@gmail.com", 
                    "alias": "monica", 
                    "id": 6
                },
                {
                    "forward": "dinesh.chugtai@gmail.com", 
                    "alias": "dinesh", 
                    "id": 7
                },
                {
                    "forward": "bertram.gilfoyle@gmail.com", 
                    "alias": "bertram", 
                    "id": 8
                },
                {
                    "forward": "nelson.bighetti@gmail.com", 
                    "alias": "nelson", 
                    "id": 9
                }
            ]
        }
    ], 
    "total": 3,
    "success": true
}

You can use the q parameter to search domains that starts by the given value.

Eg:

GET /v2/domains/?q=faceb

{
    "domains": [
        {
            "active": true, 
            "domain": "facebook.com", 
            "added": 1559639727000, 
            "daily_quota": 500, 
            "aliases": [
                {
                    "forward": "mark@facebook-mail.com", 
                    "alias": "*", 
                    "id": 3
                }
            ]
        }
    ], 
    "total": 1,
    "success": true
}

POST /v2/domains/

Add a new domain

Send a POST request containing a JSON payload with the following parameters

POST /v2/domains/ -H application/json {"domain": "newdomain.com"}

Parameter Required? Type Description
domain True String Name of the domain

When successful, the server will return the newly created domain as JSON response:

{
    "domain": {
        "active": false, 
        "domain": "newdomain.com", 
        "added": 1559652806000, 
        "daily_quota": 500, 
        "aliases": [
            {
                "forward": "contact@your-company.tld", 
                "alias": "*", 
                "id": 12
            }
        ]
    }, 
    "success": true
}

GET /v2/domains/:domain

Get the details of a domain

GET /v2/domains/piedpiper.com

Returns a JSON object like the following:

{
    "active": false, 
    "domain": "piedpiper.com", 
    "added": 1559639733000, 
    "daily_quota": 500, 
    "aliases": [
        {
            "forward": "richard.hendricks@gmail.com", 
            "alias": "richard", 
            "id": 4
        },
        {
            "forward": "jared.dunn@gmail.com", 
            "alias": "jared", 
            "id": 5
        },
        {
            "forward": "monica.hall@gmail.com", 
            "alias": "monica", 
            "id": 6
        },
        {
            "forward": "dinesh.chugtai@gmail.com", 
            "alias": "dinesh", 
            "id": 7
        },
        {
            "forward": "bertram.gilfoyle@gmail.com", 
            "alias": "bertram", 
            "id": 8
        },
        {
            "forward": "nelson.bighetti@gmail.com", 
            "alias": "nelson", 
            "id": 9
        }
    ]
}

DELETE /v2/domains/:domain

Delete a given domain

DELETE /v2/domains/piedpiper.com

{
    "success": true
}

POST /v2/domains/:domain/check

Check if the MX entires are valid for a domain

POST /v2/domains/piedpiper.com/check -H application/json

{ "reason": null, "success": true }

The endpoint will return true in success when the MX are well configured, false otherwise.

reason might contain a specific reason why the entries are not valid. If the value is null, it's often because the MX values are invalid.

Aliases

POST /v2/domains/:domain/aliases/

Add a new alias to a given domain

POST /v2/domains/piedpiper.com/aliases/ -H application/json {"alias": "richard", "forward": "richard.hendricks@gmail.com"}

Parameter Required? Type Description
alias True String Alias to be used in front of your domain, like "contact", "info", etc
forward True String - email Destination email to forward the emails to
{
    "alias": {
        "forward": "richard.hendricks@gmail.com", 
        "alias": "richard", 
        "id": 11
    }, 
    "success": true
}

PUT /v2/domains/:domain/aliases/:alias

Update a given alias

PUT /v2/domains/piedpiper.com/aliases/richard -H application/json {"forward": "richard.hendricks@protonmail.com"}

Parameter Required? Type Description
forward True String - email Destination email to forward the emails to
{
    "alias": {
        "forward": "richard.hendricks@protonmail.com", 
        "alias": "richard", 
        "id": 11
    }, 
    "success": true
}

DELETE /v2/domains/:domain/aliases/:alias

Delete the given alias

DELETE /v2/domains/piedpiper.com/aliases/nelson

{
    "success": true
}

Logs

GET /v2/domains/:domain/logs

Retrive the logs for a given domain

GET /v2/domains/piedpiper.com/logs

Returns a JSON object like the following:

{
    "logs": [
        {
            "sender": {
                "email": "someone@some-domain.com", 
                "name": "Someone"
            }, 
            "created": "2019-01-13 00:00:42+0000", 
            "hostname": "mx1b.improvmx.com", 
            "host_ip": "145.239.196.139", 
            "forward": {
                "email": "richard.hendricks@protonmail.com", 
                "name": "Richard Hendricks"
            }, 
            "messageId": "<20190112230013.7A72C1F718@mx1b.improvmx.com>", 
            "created_raw": "Sun, 13 Jan 2019 00:00:42 GMT", 
            "recipient": {
                "email": "richard@piedpiper.com", 
                "name": 'Richard Hendricks'
            }, 
            "events": [
                {
                    "status": "DELIVERED", 
                    "code": 250, 
                    "created": "2019-01-12 23:01:21+0000", 
                    "ip": "cloud2.cloudmailin.net", 
                    "server": "mx1a.improvmx.com", 
                    "message": "Sent."
                }
            ], 
            "subject": "Investment opportunities!"
        }
    ], 
    "success": true, 
    "mxes": [
        "mx2.improvmx.com", 
        "mx1.improvmx.com"
    ]
}

The logs array will contain all the processed emails. Each entry in the array will contain a list of events, related to all the actions taken by the ImprovMX servers, which are:

  • QUEUED - The email was accepted to be processed
  • REFUSED - The email was refused at the SMTP connection
  • DELIVERED - The email was successfully delivered to the end destination
  • SOFT-BOUNCE - The end destination refused the email temporarily
  • HARD-BOUNCE - The end destination couldn't accept the email definitively.

GET /v2/domains/:domain/logs/:alias

Retrieve the logs for a given alias in a given domain

GET /v2/domains/piedpiper.com/logs/richard

Behave the same as the general logs, but returns only for the specificly given alias.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment