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
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.