API Reference

Programmatically manage your domains and aliases for email forwarding.

This is the documentation for ImprovMX HTTP REST API endpoints, which let you fully programmatically manage your domains and aliases for email forwarding.

Base URL

https://api.improvmx.com/v3

Authentication

First, retrieve your API Key from the API page of the ImprovMX app dashboard. Authentication is done via basic access authentication. Pass the string api as the username and your API key as the password.

curl https://api.improvmx.com/v3/domains \
  -H "Authorization: Basic api:$API_KEY"

HTTP Error Codes

When an error occurs, the response body will contain a JSON object explaining the reason for the failure.

Code	Description
200	Success — The request was successful
400	Bad Request — Incorrect or missing parameter
401	Authentication required — Not properly authenticated
403	Forbidden — Lack permissions or premium account required
500	Server error — Bug encountered

Example error response

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

Account

GET /account

Retrieve details about your account, including billing info, plan details, and usage limits.

Request

curl -X GET https://api.improvmx.com/v3/account \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "account": {
        "billing_email": null,
        "cancels_on": null,
        "card_brand": "Visa",
        "company_details": "1 Decentralized Street\n92024-2852 California",
        "company_name": "PiedPiper Inc.",
        "company_vat": null,
        "country": "US",
        "created": 1512139382000,
        "email": "richard.hendricks@gmail.com",
        "last4": "1234",
        "limits": {
            "aliases": 10000,
            "daily_quota": 100000,
            "daily_send": 200,
            "domains": 10000,
            "ratelimit": 10,
            "redirections": 50,
            "subdomains": 2,
            "api": 3,
            "credentials": 50,
            "destinations": 5
        },
        "lock_reason": null,
        "locked": null,
        "password": true,
        "plan": {
            "aliases_limit": 10000,
            "daily_quota": 100000,
            "display": "Business - $249",
            "domains_limit": 10000,
            "kind": "enterprise",
            "name": "enterprise249",
            "price": 249,
            "yearly": false
        },
        "premium": true,
        "privacy_level": 1,
        "renew_date": 15881622590000
    },
    "success": true
}

GET /account/whitelabels

List all whitelabel domains configured on your account.

Request

curl -X GET https://api.improvmx.com/v3/account/whitelabels \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "whitelabels": [
        {
            "name": "piedpiper.com"
        }
    ],
    "success": true
}

Domains

GET /domains

List all domains on your account. Results are paginated.

Parameter	Type	Description
q	string	Search for domains starting with this value
is_active	boolean	Filter by active/inactive status
limit	integer	Results per page (5–100, default 50)
page	integer	Page number (1-based)

Request

curl -X GET https://api.improvmx.com/v3/domains \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "domains": [
        {
            "active": true,
            "domain": "google.com",
            "display": "google.com",
            "dkim_selector": "dkimprovmx",
            "notification_email": null,
            "webhook": null,
            "whitelabel": null,
            "added": 1559639697000,
            "aliases": [
                {
                    "created": 1702393755000,
                    "forward": "sergey@gmail.com",
                    "alias": "sergey",
                    "id": 1
                },
                {
                    "created": 1702393755000,
                    "forward": "larry@gmail.com",
                    "alias": "larry",
                    "id": 2
                }
            ]
        },
        {
            "active": false,
            "domain": "piedpiper.com",
            "display": "piedpiper.com",
            "dkim_selector": "dkimprovmx",
            "notification_email": null,
            "whitelabel": null,
            "added": 1559639733000,
            "aliases": [
                {
                    "created": 1702393755000,
                    "forward": "richard.hendricks@gmail.com",
                    "alias": "richard",
                    "id": 4
                },
                {
                    "created": 1702393755000,
                    "forward": "jared.dunn@gmail.com",
                    "alias": "jared",
                    "id": 5
                }
            ]
        }
    ],
    "total": 3,
    "limit": 50,
    "page": 1,
    "success": true
}

POST /domains

Add a new domain to your account. A default catch-all alias will be created automatically.

Parameter	Type	Description
domain required	string	Domain name to add
notification_email	string	Notification recipient email
whitelabel	string	Parent domain for DNS display

Request

curl -X POST https://api.improvmx.com/v3/domains \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"domain": "piedpiper.com"}'

Show response

{
    "domain": {
        "active": false,
        "domain": "piedpiper.com",
        "display": "piedpiper.com",
        "dkim_selector": "dkimprovmx",
        "notification_email": null,
        "whitelabel": null,
        "added": 1559652806000,
        "aliases": [
            {
                "forward": "contact@piedpiper.com",
                "alias": "*",
                "id": 12
            }
        ]
    },
    "success": true
}

GET /domains/:domain

Get details for a specific domain. Limited to 200 aliases; use the aliases endpoint for larger sets.

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "domain": {
        "active": false,
        "domain": "piedpiper.com",
        "added": 1559639733000,
        "display": "piedpiper.com",
        "dkim_selector": "dkimprovmx",
        "notification_email": null,
        "webhook": null,
        "whitelabel": null,
        "aliases": [
            {
                "created": 1702393755000,
                "forward": "richard.hendricks@gmail.com",
                "alias": "richard",
                "id": 4
            },
            {
                "created": 1702393755000,
                "forward": "jared.dunn@gmail.com",
                "alias": "jared",
                "id": 5
            }
        ]
    },
    "success": true
}

PUT /domains/:domain

Update settings for a domain. The domain name itself cannot be changed.

Parameter	Type	Description
notification_email	string	Notification email address
webhook	string	Event webhook endpoint URL
whitelabel	string	Parent domain for whitelabeling

Request

curl -X PUT https://api.improvmx.com/v3/domains/piedpiper.com \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"notification_email": "email@example.com", "webhook": "https://requestbin.com/r/abc123", "whitelabel": "hooli.com"}'

Show response

{
    "domain": {
        "active": false,
        "domain": "piedpiper.com",
        "added": 1559639733000,
        "display": "piedpiper.com",
        "dkim_selector": "dkimprovmx",
        "notification_email": "email@example.com",
        "webhook": "https://requestbin.com/r/enbwnegkb25v",
        "whitelabel": "hooli.com",
        "aliases": [
            {
                "forward": "richard.hendricks@gmail.com",
                "alias": "richard",
                "id": 4
            },
            {
                "forward": "jared.dunn@gmail.com",
                "alias": "jared",
                "id": 5
            }
        ]
    },
    "success": true
}

DELETE /domains/:domain

Delete a domain and all its aliases.

Request

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "success": true
}

GET /domains/:domain/check

Check the DNS configuration for a domain. Returns validation status for MX, SPF, DKIM, and DMARC records with expected vs. actual values.

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/check \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "records": {
        "provider": "cloudflare",
        "advanced": true,
        "dkim1": {
            "expected": "dkimprovmx1.improvmx.com.",
            "valid": true,
            "values": "dkimprovmx1.improvmx.com."
        },
        "dkim2": {
            "expected": "dkimprovmx2.improvmx.com.",
            "valid": true,
            "values": "dkimprovmx2.improvmx.com."
        },
        "dmarc": {
            "expected": "v=DMARC1; p=none;",
            "valid": false,
            "values": null
        },
        "error": null,
        "mx": {
            "expected": [
                "mx1.improvmx.com",
                "mx2.improvmx.com"
            ],
            "valid": true,
            "values": [
                "mx2.improvmx.com",
                "mx1.improvmx.com"
            ]
        },
        "spf": {
            "expected": "v=spf1 include:someservice.org include:spf.improvmx.com ~all",
            "valid": false,
            "values": "v=spf1 include:someservice.org ~all"
        },
        "valid": false
    },
    "success": true
}

Aliases

GET /domains/:domain/aliases

List all aliases for a domain.

Parameter	Type	Description
q	string	Search alias and destination starting values
alias	string	Filter by alias name prefix
page	integer	Page number (1-based)

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/aliases \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "aliases": [
        {
            "created": 1702982672000,
            "forward": "richard.hendricks@gmail.com",
            "alias": "richard",
            "id": 4
        },
        {
            "created": 1702982672000,
            "forward": "jared.dunn@gmail.com",
            "alias": "jared",
            "id": 5
        }
    ],
    "limit": 5,
    "page": 1,
    "total": 2,
    "success": true
}

POST /domains/:domain/aliases

Create a new alias for a domain.

Parameter	Type	Description
alias required	string	Alias prefix (e.g., "contact")
forward required	string	Comma-separated destination email(s) and/or webhook URLs

Request

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/aliases \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"alias": "richard", "forward": "richard.hendricks@gmail.com"}'

Show response

{
    "alias": {
        "forward": "richard.hendricks@gmail.com",
        "alias": "richard",
        "id": 11
    },
    "success": true
}

GET /domains/:domain/aliases/:alias

Get details for a specific alias. You can use the alias name or numeric ID as the path parameter.

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/aliases/richard \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "alias": {
        "created": 1702982672000,
        "forward": "richard.hendricks@protonmail.com",
        "alias": "richard",
        "id": 11
    },
    "success": true
}

PUT /domains/:domain/aliases/:alias

Update the forward destination for an alias.

Parameter	Type	Description
forward required	string	New destination email(s) or webhooks

Request

curl -X PUT https://api.improvmx.com/v3/domains/piedpiper.com/aliases/richard \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"forward": "richard.hendricks@protonmail.com"}'

Show response

{
    "alias": {
        "forward": "richard.hendricks@protonmail.com",
        "alias": "richard",
        "id": 11
    },
    "success": true
}

DELETE /domains/:domain/aliases/:alias

Delete a specific alias.

Request

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/aliases/richard \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "success": true
}

DELETE /domains/:domain/aliases/aliases-all

Delete all aliases for a domain.

Request

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/aliases/aliases-all \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "success": true
}

POST /domains/:domain/aliases/bulk

Bulk add, update, or delete aliases. Up to 500 aliases per request.

Parameter	Type	Description
aliases required	array	Array of objects with "alias" and "forward" fields
behavior	string	"add" (default), "update", or "delete"

Request

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/aliases/bulk \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"aliases":[{"alias":"richard","forward":"richard.hendricks@gmail.com"},{"alias":"jared","forward":"jared.dunn@gmail.com"}],"behavior":"update"}'

Show response

{
    "added": [
        {
            "alias": "richard",
            "forward": "richard.hendricks@gmail.com",
            "id": 12345
        },
        {
            "alias": "jared",
            "forward": "jared.dunn@gmail.com",
            "id": 12346
        }
    ],
    "failed": [
        {
            "alias": "monica",
            "forward": "monica.hall@gmail.com",
            "id": 12347
        }
    ],
    "success": true,
    "updated": [
        {
            "alias": "dinesh",
            "forward": "dinesh.chugtai@gmail.com",
            "id": 12348
        },
        {
            "alias": "bertram",
            "forward": "bertram.gilfoyle@gmail.com",
            "id": 12349
        }
    ]
}

Rules

Rules allow advanced email routing using conditional logic. There are three rule types:

Alias Rules

{
  "alias": "string",
  "forward": "string"
}

Regex Rules

{
  "regex": "string",
  "scopes": ["sender",
    "recipient",
    "subject", "body"],
  "forward": "string"
}

CEL Rules

{
  "expression": "string",
  "forward": "string"
}

GET /domains/:domain/rules

List all rules for a domain.

Parameter	Type	Description
search	string	Filter rules by string match
page	integer	Page number (1-based)

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/rules \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "limit": 100,
    "page": 1,
    "rules": [
        {
            "active": true,
            "config": {
                "alias": "richard",
                "forward": "richard.hendricks@gmail.com"
            },
            "created": 1752026028000,
            "rank": 1.0,
            "id": "447a95d1-bac1-4d6e-8315-22b10f501efb",
            "type": "alias"
        },
        {
            "active": true,
            "config": {
                "forward": "jared.dunn@live.com",
                "regex": ".*jared.*",
                "scopes": [
                    "sender"
                ]
            },
            "created": 1752467418000,
            "rank": 2.0,
            "id": "fcadc999-0d3f-45f8-9c62-056e1b98e47a",
            "type": "regex"
        }
    ],
    "success": true,
    "total": 2
}

POST /domains/:domain/rules

Create a new rule for a domain.

Parameter	Type	Description
type required	string	"alias", "regex", or "cel"
config required	object	Rule-specific configuration object
rank	float	Priority order (higher = evaluated first)
active	boolean	Enable/disable the rule
id	string	Custom rule identifier (auto-generated if omitted)

Request

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/rules \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"regex","config":{"regex":".*important.*","scopes":["subject","body"],"forward":"richard.hendricks@gmail.com"}}'

GET /domains/:domain/rules/:rule

Get details for a specific rule.

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/rules/447a95d1-bac1-4d6e-8315-22b10f501efb \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "active": true,
    "config": {
        "alias": "richard",
        "forward": "richard.hendricks@gmail.com"
    },
    "created": 1752026028000,
    "rank": 1.0,
    "id": "447a95d1-bac1-4d6e-8315-22b10f501efb",
    "type": "alias"
}

PUT /domains/:domain/rules/:rule

Update a rule's configuration, rank, or active status.

Parameter	Type	Description
config required	object	Updated rule configuration
rank	float	New priority rank
active	boolean	Toggle active status

Request

curl -X PUT https://api.improvmx.com/v3/domains/piedpiper.com/rules/e8417681-3a4c-4f9b-ab93-1ca2529036c9 \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"config":{"regex":".*critical.*","scopes":["subject","body"],"forward":"richard.hendricks@gmail.com"}}'

Show response

{
    "rule": {
        "active": true,
        "config": {
            "regex": ".*critical.*",
            "scopes": ["subject", "body"],
            "forward": "richard.hendricks@gmail.com"
        },
        "created": 1752026028,
        "id": "447a95d1-bac1-4d6e-8315-22b10f501efb",
        "rank": 1.0,
        "type": "alias"
    },
    "success": true
}

DELETE /domains/:domain/rules/:rule

Delete a specific rule.

Request

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/rules/e8417681-3a4c-4f9b-ab93-1ca2529036c9 \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "success": true
}

DELETE /domains/:domain/rules-all

Delete all rules for a domain.

Request

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/rules-all \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "success": true
}

POST /domains/:domain/rules/bulk

Bulk add, update, or delete rules.

Parameter	Type	Description
rules required	array	Array of rule configuration objects
behavior	string	"add" (default), "update", or "delete"

Request — Add

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/rules/bulk \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"behavior":"add","rules":[{"type":"cel","config":{"expression":"true","forward":"richard.hendricks@gmail.com"}}]}'

Request — Update

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/rules/bulk \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"behavior":"update","rules":[{"id":"62f9cf67-9005-41a6-8706-843ca8df8932","config":{"alias":"gavin.belson@gmail.com"}},{"id":"5742c992-4378-4412-945b-be2177072fc4","config":{"regex":".*finance.*"}}]}'

Request — Delete

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/rules/bulk \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"behavior":"delete","rules":[{"id":"62f9cf67-9005-41a6-8706-843ca8df8932"},{"id":"48ec8f60-ea1f-4509-9c36-43f5e83170b5"}]}'

Show response (update example)

{
    "errors": [],
    "results": [
        {
            "operation": "update",
            "rule": {
                "active": true,
                "config": {
                    "alias": "gavin@gmail.com",
                    "forward": "gavin.belson@gmail.com"
                },
                "created": 1752514190,
                "id": "62f9cf67-9005-41a6-8706-843ca8df8932",
                "rank": 50.0,
                "type": "alias"
            },
            "success": true
        },
        {
            "operation": "update",
            "rule": {
                "active": true,
                "config": {
                    "forward": "jared.dunn@live.com",
                    "regex": ".+",
                    "scopes": [
                        "subject",
                        "body"
                    ]
                },
                "created": 1752510060,
                "id": "5742c992-4378-4412-945b-be2177072fc4",
                "rank": 40.0,
                "type": "regex"
            },
            "success": true
        }
    ],
    "success": true
}

Logs

Monitor email forwarding activity and troubleshoot delivery issues. Event statuses include: QUEUED, REFUSED, DELIVERED, SOFT-BOUNCE, HARD-BOUNCE.

GET /domains/:domain/logs

List email logs for a domain.

Parameter	Type	Description
next_cursor	string	Pagination token (log.id format)

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/logs \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "logs": [
        {
            "created": "2020-01-25 12:19:09+0000",
            "created_raw": "Sat, 25 Jan 2020 12:19:09 GMT",
            "events": [
                {
                    "code": 250,
                    "created": "2020-01-25 12:19:11+0000",
                    "id": "some_random_id",
                    "local": "mxb.infra.improvmx.com",
                    "message": "Queued",
                    "server": "mail-io1-f54.google.com",
                    "status": "QUEUED"
                },
                {
                    "code": 250,
                    "created": "2020-01-25 12:19:12+0000",
                    "id": "some_random_id",
                    "local": "gmail-smtp-in.l.google.com",
                    "message": "Sent.",
                    "server": "mail16.mxc.infra.improvmx.com",
                    "status": "DELIVERED"
                }
            ],
            "forward": {
                "email": "richard.hendricks@gmail.com",
                "name": "Richard Hendricks"
            },
            "hostname": "mail-io1-f54.google.com",
            "id": "20201002014128.5ea8ee59fa894aa7a9141e9665985b46",
            "messageId": "some_random_id",
            "recipient": {
                "email": "richard@piedpiper.com",
                "name": "Richard Hendricks"
            },
            "sender": {
                "email": "gavin@hooli.com",
                "name": "Gavin Belsonx"
            },
            "subject": "You are screwed, Piedpiper team!",
            "transport": "smtp"
        }
    ],
    "success": true
}

GET /domains/:domain/logs/:alias

List email logs for a specific alias.

Parameter	Type	Description
next_cursor	string	Pagination token

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/logs/richard \
  -H "Authorization: Basic api:$API_KEY"

GET /domains/:domain/logs/search

Search through email logs with filters.

Parameter	Type	Description
filter	string	"all" (default) or "failure"
text	string	Case-insensitive search for subject/sender/recipient
order	string	"desc" (default) or "asc"
after required	integer	Unix timestamp (seconds) for start range
before required	integer	Unix timestamp (seconds) for end range

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/logs/search \
  -H "Authorization: Basic api:$API_KEY" \
  -G \
  --data-urlencode "filter=all" \
  --data-urlencode "text=keyword" \
  --data-urlencode "order=desc" \
  --data-urlencode "after=1715500000" \
  --data-urlencode "before=1715600000"

SMTP Credentials

Manage SMTP credentials to send emails via ImprovMX relay. This is a premium feature.

GET /domains/:domain/credentials

List all SMTP credentials for a domain.

Request

curl -X GET https://api.improvmx.com/v3/domains/piedpiper.com/credentials \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "credentials": [
        {
            "created": 1581604970000,
            "usage": 0,
            "username": "richard"
        },
        {
            "created": 1581607028000,
            "usage": 0,
            "username": "monica"
        }
    ],
    "success": true
}

POST /domains/:domain/credentials

Create a new SMTP credential. The first credential for a domain requires DNS DKIM CNAME entries and DMARC TXT record updates.

Parameter	Type	Description
username required	string	Mailbox prefix (e.g., "bighead" for bighead@domain.com)
password required	string	Account password

Request

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/credentials \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"username":"bighead","password":"abc123"}'

Show response

{
    "credential": {
        "created": 1588236952000,
        "usage": 0,
        "username": "bighead"
    },
    "requires_new_mx_check": false,
    "success": true
}

PUT /domains/:domain/credentials/:username

Update the password for an SMTP credential.

Parameter	Type	Description
password required	string	New password

Request

curl -X PUT https://api.improvmx.com/v3/domains/piedpiper.com/credentials/bighead \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"password":"abcd1234"}'

Show response

{
    "credential": {
        "created": 1588236952000,
        "usage": 0,
        "username": "bighead"
    },
    "success": true
}

DELETE /domains/:domain/credentials/:username

Delete an SMTP credential.

Request

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/credentials/russ \
  -H "Authorization: Basic api:$API_KEY"

Show response

{
    "success": true
}

Still have questions? Feel free to reach out to our support team!