Our email forwarding API

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

Base URL

The base URL of ImprovMX’s API can be accessed at

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

Authentication

First, you need to retrieve your API Key by visiting the API page on your ImprovMX app dashboard.

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:

Authentication: Basic api:{your_api_key}

That’s it, you are now ready to communicate with our API!

Error codes

Here are the main error codes you will encounter:

CodeDescription
200Success
This means the request was successfully made
400Bad Request
This means you passed a wrong or missing parameter
403Forbidden
The API key you provided is not valid or you are trying to access a protected resource
500Server 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 detail what was the reason for the failure. This should 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 ImprovMX 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
}

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 also use the q parameter to search domains that starts with 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/

Adding a new domain

To 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”}

ParameterRequired?TypeDescription
domainTrueStringName 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 entries 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“}

ParameterRequired?TypeDescription
aliasTrueStringAlias to be used in front of your domain, like “contact”, “info”, etc
forwardTrueString – emailDestination 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“}

ParameterRequired?TypeDescription
forwardTrueString – emailDestination 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

Retrieve 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

This behaves similarly as the general logs but returns results only for the requested alias.