API Reference Guide

Our HTTP REST API lets you programmatically manage your domains and aliases for email forwarding.

Base URL

The base URL is: https://api.improvmx.com/v3

Versioning

The v3 api was released on April 30th, 2020.

The v2 api has been marked as deprecated and was removed on June 1st 2024.

Authentication

Get your API key from the API page of the dashboard, then use HTTP basic auth with username api and your API key as the password:

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

Error codes

CODE	DESCRIPTION
200	Success
400	Bad Request - Incorrect or missing parameter.
401	Authentication required - Missing or invalid credentials.
403	Forbidden - Missing permissions, e.g. requires a premium account.
500	Server error - We ran into a bug. Let us know and we'll fix it.

Errors return a JSON body explaining the failure. Example Bad Request:

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

Account

Get account

GET /account

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

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": "[email protected]",
        "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
}

{
    "account": {
        "address": "1 Decentralized Street, 92024 California",
        "billing_email": null,
        "cancels_at": null,
        "company_vat": null,
        "country": "US",
        "created_at": "2017-12-01T13:23:02Z",
        "email": "[email protected]",
        "email_log_retention_days": 7,
        "lock_reason": null,
        "locked": null,
        "name": "PiedPiper Inc.",
        "over_quota": false,
        "plan": {
            "name": "Enterprise - PiedPiper",
            "price": 249,
            "billing_cycle": "monthly",
            "domains_limit": 10000,
            "aliases_limit": 10000,
            "rules_limit": 50,
            "daily_receive_limit": 100000,
            "daily_send_limit": 200,
            "monthly_receive_limit": 0,
            "monthly_send_limit": 0
        },
        "privacy_level": 1,
        "renews_at": "2020-04-30T07:50:59Z"
    }
}

List whitelabel domains

GET /account/whitelabels

Lists whitelabels for your domain.

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

Response:

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

Domains

Add domains to ImprovMX that you want to send/receive emails from.

List domains

GET /domains

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`q`	String	False	Filter domains by substring.
`is_active`	Boolean	False	Active (`1`) or inactive (`0`) only.
`limit`	Integer	False	Number of domains. Default 50, max 100.
`page`	Integer	False	Page number (1-based, default 1).

Limited to 200 aliases per domain. For more, use the list aliases endpoint.

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": "[email protected]",
                    "alias": "sergey",
                    "id": 1
                },
                {
                    "created": 1702393755000,
                    "forward": "[email protected]",
                    "alias": "larry",
                    "id": 2
                }
            ]
        },
        {
            "active": false,
            "domain": "piedpiper.com",
            "display": "piedpiper.com",
            "dkim_selector": "dkimprovmx",
            "notification_email": null,
            "webhook": null,
            "whitelabel": null,
            "added": 1559639733000,
            "aliases": [
                {
                    "created": 1702393755000,
                    "forward": "[email protected]",
                    "alias": "richard",
                    "id": 4
                },
                {
                    "created": 1702393755000,
                    "forward": "[email protected]",
                    "alias": "jared",
                    "id": 5
                }
            ]
        }
    ],
    "total": 2,
    "limit": 50,
    "page": 1,
    "success": true
}

Use q to filter domains by substring:

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

Response:

{
    "domains": [
        {
            "active": true,
            "domain": "piedpiper.com",
            "display": "piedpiper.com",
            "dkim_selector": "dkimprovmx",
            "notification_email": null,
            "webhook": null,
            "whitelabel": null,
            "added": 1559639727000,
            "daily_quota": 500,
            "aliases": [
                {
                    "created": 1702393755000,
                    "forward": "[email protected]",
                    "alias": "*",
                    "id": 3
                }
            ]
        }
    ],
    "total": 1,
    "limit": 50,
    "page": 1,
    "success": true
}

Get domain

GET /domains/:domain

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

Limited to 200 aliases per domain. For more, use the list aliases endpoint.

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": "[email protected]",
                "alias": "richard",
                "id": 4
            },
            {
                "created": 1702393755000,
                "forward": "[email protected]",
                "alias": "jared",
                "id": 5
            }
        ]
    },
    "success": true
}

Add domain

POST /domains

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`domain`	String	True	Domain name.
`notification_email`	String	False	Where to send notifications.
`whitelabel`	String	False	Parent domain shown in DNS settings.

Response:

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

Update domain

PUT /domains/:domain

The domain name cannot be changed.

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 protected]",
      "webhook": "https://requestbin.com/r/abc123",
      "whitelabel": "hooli.com"
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`notification_email`	String	False	Where to send domain notifications.
`webhook`	String (URL)	False	Where to POST email events for this domain.
`whitelabel`	String	False	Parent domain owner.

Response:

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

Verify domain

GET /domains/:domain/check

Verifies the domain's MX, SPF, DKIM, and DMARC records are configured correctly. Once verified, our servers will begin forwarding.

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

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
}

Returns success: true when MX is configured correctly. error contains the reason when not.

Delete domain

DELETE /domains/:domain

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

Response:

{
    "success": true
}

Aliases

Aliases are mailbox identities under your domain, i.e. [email protected] -> [email protected]

List aliases

GET /domains/:domain/aliases

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`q`	String	False	Filter alias and destination by substring.
`alias`	String	False	Filter alias by prefix.
`limit`	Integer	False	Number of aliases. Default 20, max 100.
`page`	Integer	False	Page number (1-based, default 1).

Response:

{
    "aliases": [
        {
            "created": 1702982672000,
            "forward": "[email protected]",
            "alias": "richard",
            "id": 4
        },
        {
            "created": 1702982672000,
            "forward": "[email protected]",
            "alias": "jared",
            "id": 5
        }
    ],
    "limit": 20,
    "page": 1,
    "total": 2,
    "success": true
}

Get alias

GET /domains/:domain/aliases/:alias

alias can be a string (richard) or the int id (11) returned at creation.

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

Response:

{
    "alias": {
        "created": 1702982672000,
        "forward": "[email protected]",
        "alias": "richard",
        "id": 11
    },
    "success": true
}

Add alias

POST /domains/:domain/aliases

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": "[email protected]"
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`alias`	String	True	Local part of the address (e.g. `contact`, `info`).
`forward`	String	True	Comma-separated destination emails and/or webhooks.

Response:

{
    "alias": {
        "forward": "[email protected]",
        "alias": "richard",
        "id": 11
    },
    "success": true
}

Add aliases

POST /domains/:domain/aliases/batch

Batch-create aliases. Returns successful and failed entries separately — partial failures don't fail the request.

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/aliases/batch \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "aliases": [
          {"alias": "richard", "forward": "[email protected]"},
          {"alias": "jared", "forward": "[email protected]"}
      ]
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`aliases`	Array	True	Up to 500 objects, each with `alias` and `forward`.

Response:

{
    "added": [
        {
            "alias": "richard",
            "forward": "[email protected]",
            "id": 12345,
            "created_at": "2026-05-05T11:32:00Z",
            "updated_at": "2026-05-05T11:32:00Z"
        },
        {
            "alias": "jared",
            "forward": "[email protected]",
            "id": 12346,
            "created_at": "2026-05-05T11:32:00Z",
            "updated_at": "2026-05-05T11:32:00Z"
        }
    ],
    "failed": []
}

Update alias

PUT /domains/:domain/aliases/:alias

alias can be a string (richard) or the int id ( 11) returned at creation.

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": "[email protected]"
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`forward`	String	True	Comma-separated destination emails and/or webhooks.

Response:

{
    "alias": {
        "forward": "[email protected]",
        "alias": "richard",
        "id": 11
    },
    "success": true
}

Update aliases

POST /domains/:domain/aliases/bulk

Batch-update aliases. Returns successful and failed entries separately — partial failures don't fail the 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":"[email protected]"},
         {"alias":"jared", "forward":"[email protected]"}]
      "behavior": "update"}'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`aliases`	Array	True	Up to 500 objects with `alias` and `forward`.
`behavior`	String	False	"add" (default) fails if alias exists, "update" updates an existing alias, "delete" deletes specified aliases.

Response (add/update):

{
    "added": [
        {
            "alias": "richard",
            "forward": "[email protected]",
            "id": 12345
        },
        {
            "alias": "jared",
            "forward": "[email protected]",
            "id": 12346
        }
    ],
    "failed": [
        {
            "alias": "monica",
            "forward": "[email protected]",
            "id": 12347
        }
    ],
    "success": true,
    "updated": [
        {
            "alias": "dinesh",
            "forward": "[email protected]",
            "id": 12348
        },
        {
            "alias": "bertram",
            "forward": "[email protected]",
            "id": 12349
        }
    ]
}

Response (delete):

{
    "deleted": [
        {
            "alias": "test",
            "created": 1743462739000,
            "forward": "[email protected]",
            "id": 6
        }
    ],
    "failed": [
        {
            "alias": "test1"
        }
    ],
    "success": true
}

Update aliases

PUT /domains/:domain/aliases/batch

Bulk-update aliases by id. Returns successful and failed entries separately — partial failures don't fail the request.

curl -X PUT https://api.improvmx.com/v3/domains/piedpiper.com/aliases/batch \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "aliases": [
          {"id": 12345, "forward": "[email protected]"},
          {"id": 12346, "forward": "[email protected]"}
      ]
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`aliases`	Array	True	Up to 500 objects, each with a numeric `id` and the fields to update (e.g. `forward`).

Response:

{
    "updated": [
        {
            "alias": "richard",
            "forward": "[email protected]",
            "id": 12345,
            "created_at": "2026-05-05T11:32:00Z",
            "updated_at": "2026-05-05T12:00:00Z"
        }
    ],
    "failed": [
        {
            "id": 999999,
            "forward": "[email protected]",
            "error": "Alias not found."
        }
    ]
}

Delete alias

DELETE /domains/:domain/aliases/:alias

alias can be a string (richard) or the int id (11) returned at creation.

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

Response:

{
    "success": true
}

Delete aliases

DELETE /domains/:domain/aliases/batch

Bulk-delete aliases by id. Returns successful and failed entries separately — partial failures don't fail the request.

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/aliases/batch \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"ids": [12345, 12346, 12347]}'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`ids`	Array	True	Up to 500 alias ids (integers) to delete.

Response:

{
    "deleted": [12345, 12346],
    "failed": [
        {
            "id": 12347,
            "error": "Alias not found."
        }
    ]
}

Delete all aliases

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

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

Returns 204 No Content on success.

Response:

{
    "success": true
}

Rules

Rules are used to route incoming email to specific destinations based on various criteria.

There are several types of rules described below.

Alias rule config

Schema for adding or updating alias rules.

{
    "alias": "richard",
    "forward": "[email protected]"
}

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`alias`	String	True	Alias this rule matches.
`forward`	String	True	Comma-separated forwarding destinations.

Regex rule config

Schema for adding or updating regex rules.

{
    "forward": "[email protected]",
    "regex": ".*jared.*",
    "scopes": [
        "sender",
        "recipient",
        "subject",
        "body"
    ]
}

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`regex`	String	True	Regex pattern to match.
`scopes`	String List	True	Match scopes: `sender`, `recipient`, `subject`, `body`.
`forward`	String	True	Comma-separated forwarding destinations.

CEL rule config

Schema for adding or updating CEL rules.

{
    "expression": "subject.contains('finance')",
    "forward": "[email protected]"
}

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`expression`	String	True	CEL expression to match.
`forward`	String	True	Comma-separated forwarding destinations.

List rules

GET /domains/:domain/rules

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`search`	String	False	Filter rules by substring.
`limit`	Integer	False	Number of rules. Default 100, max 100.
`page`	Integer	False	Page number (1-based, default 1).

Response:

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

Add rule

POST /domains/:domain/rules

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": "[email protected]"
      }
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`type`	String	True	One of `alias`, `regex`, or `cel`.
`config`	JSON	True	JSON config for the rule (varies by type).
`rank`	Float	False	Rank determining evaluation priority. Defaults to the next largest rank.
`active`	Boolean	False	Whether the rule is active.
`id`	String	False	Rule ID. Auto-generated UUID if omitted.

Response:

{
    "rule": {
        "active": true,
        "config": {
            "alias": "richard",
            "forward": "[email protected]"
        },
        "created": 1752026028000,
        "rank": 1.0,
        "id": "447a95d1-bac1-4d6e-8315-22b10f501efb",
        "type": "alias"
    },
    "success": true
}

Add rules

POST /domains/:domain/rules/batch

Bulk-create rules. Returns successful and failed entries separately — partial failures don't fail the request.

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`rules`	Array	True	Up to 500 rule objects, each with `type` and `config` (and optionally `rank`, `active`, `id`).

Response:

{
    "added": [
        {
            "active": true,
            "config": {
                "alias": "richard",
                "forward": "[email protected]"
            },
            "created_at": "2026-05-05T11:32:00Z",
            "updated_at": "2026-05-05T11:32:00Z",
            "id": "62f9cf67-9005-41a6-8706-843ca8df8932",
            "rank": 50.0,
            "type": "alias"
        }
    ],
    "failed": [
        {
            "type": "regex",
            "config": {
                "regex": ".*finance.*",
                "scopes": ["subject"],
                "forward": "not-an-email"
            },
            "error": "Invalid forward address."
        }
    ]
}

Get rule

GET /domains/:domain/rules/:rule

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

Response:

{
    "active": true,
    "config": {
        "alias": "richard",
        "forward": "[email protected]"
    },
    "created": 1752026028000,
    "rank": 1.0,
    "id": "447a95d1-bac1-4d6e-8315-22b10f501efb",
    "type": "alias"
}

Update rule

PUT /domains/:domain/rules/:rule

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": "[email protected]"
      }
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`config`	JSON	True	JSON config for the rule (varies by type).
`rank`	Float	False	Rank determining evaluation priority. Defaults to the next largest rank.
`active`	Boolean	False	Whether the rule is active.

Response:

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

Update rules

POST /domains/:domain/rules/bulk

# Add a rule
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": "[email protected]"
              }
          }
      ]
  }'

# Update 2 rules
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": "[email protected]"
              }
          },
          {
              "id": "5742c992-4378-4412-945b-be2177072fc4",
              "config": {
                  "regex": ".*finance.*"
              }
          }
      ]
  }'

# Delete 2 rules
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"
          }
      ]
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`rules`	List of JSON	True	List of JSON configs (varies by rule type).
`behavior`	String	False	"add" (default) fails if rule exists, "update" updates existing rules, "delete" deletes specified rules.

Response:

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

Update rules

PUT /domains/:domain/rules/batch

Bulk-update rules by id. Returns successful and failed entries separately — partial failures don't fail the request.

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`rules`	Array	True	Up to 500 objects, each with a string `id` and the fields to update (e.g. `config`, `rank`, `active`).

Response:

{
    "updated": [
        {
            "active": true,
            "config": {
                "alias": "[email protected]",
                "forward": "[email protected]"
            },
            "created_at": "2025-07-14T17:29:50Z",
            "updated_at": "2026-05-05T11:32:00Z",
            "id": "62f9cf67-9005-41a6-8706-843ca8df8932",
            "rank": 50.0,
            "type": "alias"
        }
    ],
    "failed": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "config": {"regex": ".+"},
            "error": "Rule not found."
        }
    ]
}

Delete rule

DELETE /domains/:domain/rules/:rule

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

Response:

{
    "success": true
}

Delete rules

DELETE /domains/:domain/rules/batch

Bulk-delete rules by id. Returns successful and failed entries separately — partial failures don't fail the request.

curl -X DELETE https://api.improvmx.com/v3/domains/piedpiper.com/rules/batch \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "ids": [
          "62f9cf67-9005-41a6-8706-843ca8df8932",
          "5742c992-4378-4412-945b-be2177072fc4"
      ]
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`ids`	Array	True	Up to 500 rule ids (UUID strings) to delete.

Response:

{
    "deleted": [
        "62f9cf67-9005-41a6-8706-843ca8df8932",
        "5742c992-4378-4412-945b-be2177072fc4"
    ],
    "failed": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "error": "Rule not found."
        }
    ]
}

Delete all rules

DELETE /domains/:domain/rules-all

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

Returns 204 No Content on success.

Response:

{
    "success": true
}

Logs

View the logs for your domain to see all the emails that have been sent and received.

List logs

GET /domains/:domain/logs

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`next_cursor`	String	False	Load logs after this log.id (e.g. `20201002014128.7ea8ee5b46`).

Response:

{
    "logs": [
        {
            "created": 1579954749000,
            "created_raw": 1579954749000,
            "events": [
                {
                    "code": 250,
                    "created": 1579954751000,
                    "id": "5ea8ee59-0",
                    "local": "mxb.infra.improvmx.com",
                    "message": "Queued",
                    "server": "mail-io1-f54.google.com",
                    "status": "QUEUED"
                },
                {
                    "code": 250,
                    "created": 1579954752000,
                    "id": "5ea8ee59-1",
                    "local": "gmail-smtp-in.l.google.com",
                    "message": "Sent.",
                    "server": "mail16.mxc.infra.improvmx.com",
                    "status": "DELIVERED"
                }
            ],
            "forward": {
                "email": "[email protected]",
                "name": "Richard Hendricks"
            },
            "hostname": "mail-io1-f54.google.com",
            "id": "20201002014128.5ea8ee59fa894aa7a9141e9665985b46",
            "messageId": "5ea8ee59fa894aa7a9141e9665985b46",
            "recipient": {
                "email": "[email protected]",
                "name": "Richard Hendricks"
            },
            "sender": {
                "email": "[email protected]",
                "name": "Gavin Belsonx"
            },
            "subject": "You are screwed, Piedpiper team!",
            "transport": "smtp"
        },
        {
            "created": 1579951841000,
            "created_raw": 1579951841000,
            "events": [
                {
                    "code": 550,
                    "created": 1579951842000,
                    "id": "7ea8ee59-0",
                    "local": "mxa.infra.improvmx.com",
                    "message": "5.7.1 Message considered as SPAM (Score of 5.8/5.0 with BAYES_20, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, FREEMAIL_FROM, HTML_MESSAGE, HTML_TAG_BALANCE_BODY, MIME_HEADER_CTYPE_ONLY, NO_RELAYS, URIBL_ABUSE_SURBL, URIBL_DBL_ABUSE_SPAM, URIBL_DBL_SPAM)",
                    "server": "mail-wm1-f67.google.com",
                    "status": "REFUSED"
                }
            ],
            "forward": null,
            "hostname": "mail-wm1-f67.google.com",
            "id": "20201002014128.7ea8ee59fa894aa7a91415a6659c5b46",
            "messageId": "7ea8ee59fa894aa7a91415a6659c5b46",
            "recipient": {
                "email": "[email protected]",
                "name": null
            },
            "sender": {
                "email": "[email protected]",
                "name": "ThinkTeam"
            },
            "subject": "Enlarge your (pied)piper!",
            "transport": "smtp"
        }
    ],
    "success": true
}

Each entry in logs contains a list of events. Possible statuses:

Status	Description
`QUEUED`	Accepted for processing.
`REFUSED`	Refused at the SMTP connection.
`DELIVERED`	Delivered to the destination.
`SOFT-BOUNCE`	Temporarily refused. Retried with backoff.
`HARD-BOUNCE`	Rejected by the destination.

List alias logs

GET /domains/:domain/logs/:alias

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

Same as the domain logs endpoint, scoped to one alias.

Each entry in logs contains a list of events. Possible statuses:

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`next_cursor`	String	False	Load logs after this log.id (e.g. `20201002014128.15a6659c5b46`).

Response:

{
    "logs": [
        {
            "created": 1579954749000,
            "created_raw": 1579954749000,
            "events": [
                {
                    "code": 250,
                    "created": 1579954751000,
                    "id": "5ea8ee59-0",
                    "local": "mxb.infra.improvmx.com",
                    "message": "Queued",
                    "server": "mail-io1-f54.google.com",
                    "status": "QUEUED"
                },
                {
                    "code": 250,
                    "created": 1579954752000,
                    "id": "5ea8ee59-1",
                    "local": "gmail-smtp-in.l.google.com",
                    "message": "Sent.",
                    "server": "mail16.mxc.infra.improvmx.com",
                    "status": "DELIVERED"
                }
            ],
            "forward": {
                "email": "[email protected]",
                "name": "Richard Hendricks"
            },
            "hostname": "mail-io1-f54.google.com",
            "id": "20201002014128.5ea8ee59fa894aa7a9141e9665985b46",
            "messageId": "5ea8ee59fa894aa7a9141e9665985b46",
            "recipient": {
                "email": "[email protected]",
                "name": "Richard Hendricks"
            },
            "sender": {
                "email": "[email protected]",
                "name": "Gavin Belsonx"
            },
            "subject": "You are screwed, Piedpiper team!",
            "transport": "smtp"
        },
        {
            "created": 1579951841000,
            "created_raw": 1579951841000,
            "events": [
                {
                    "code": 550,
                    "created": 1579951842000,
                    "id": "7ea8ee59-0",
                    "local": "mxa.infra.improvmx.com",
                    "message": "5.7.1 Message considered as SPAM (Score of 5.8/5.0 with BAYES_20, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, FREEMAIL_FROM, HTML_MESSAGE, HTML_TAG_BALANCE_BODY, MIME_HEADER_CTYPE_ONLY, NO_RELAYS, URIBL_ABUSE_SURBL, URIBL_DBL_ABUSE_SPAM, URIBL_DBL_SPAM)",
                    "server": "mail-wm1-f67.google.com",
                    "status": "REFUSED"
                }
            ],
            "forward": null,
            "id": "20201002014128.7ea8ee59fa894aa7a91415a6659c5b46",
            "hostname": "mail-wm1-f67.google.com",
            "messageId": "7ea8ee59fa894aa7a91415a6659c5b46",
            "recipient": {
                "email": "[email protected]",
                "name": null
            },
            "sender": {
                "email": "[email protected]",
                "name": "ThinkTeam"
            },
            "subject": "Enlarge your (pied)piper!",
            "transport": "smtp"
        }
    ],
    "success": true
}

Search logs

GET /domains/:domain/logs/search

Filter logs by timestamp window. Pass Unix seconds in after and before.

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`filter`	String	False	all (default) or failure (bounces only).
`text`	String	False	Case-insensitive match on subject, sender, recipient, or destination.
`order`	String	False	desc (default, newest first) or asc.
`after`	Integer	True	Unix seconds. Returns entries with `received_at >= after`.
`before`	Integer	True	Unix seconds. Returns entries with `received_at <= before`.

To use a human-readable date, convert to Unix seconds first (e.g. date --date='2024-07-02T12:00:00Z' +%s).

Response:

{
    "logs": [
        {
            "created": 1747043118000,
            "created_raw": 1747043118000,
            "events": [
                {
                    "code": 250,
                    "created": 1747043120000,
                    "id": "0412c5c8-0",
                    "local": "mx1.improvmx.com",
                    "message": "Queued",
                    "server": "mail-yw1-f44.google.com",
                    "status": "QUEUED"
                },
                {
                    "code": 250,
                    "created": 1747043123000,
                    "id": "0412c5c8-1",
                    "local": "gmail-smtp-in.l.google.com",
                    "message": "Sent.",
                    "server": "mail7.mxa.infra.improvmx.com",
                    "status": "DELIVERED"
                }
            ],
            "forward": {
                "email": "[email protected]",
                "name": "Richard Hendricks"
            },
            "hostname": "mail-yw1-f44.google.com",
            "id": "20250512094518.0412c5c8a4f74a82b4d02ea83404a6f1",
            "messageId": "0412c5c8a4f74a82b4d02ea83404a6f1",
            "recipient": {
                "email": "[email protected]",
                "name": null
            },
            "sender": {
                "email": "[email protected]",
                "name": "Monica Hall"
            },
            "subject": "Series A term sheet draft",
            "transport": "smtp"
        },
        {
            "created": 1747030324000,
            "created_raw": 1747030324000,
            "events": [
                {
                    "code": 250,
                    "created": 1747030325000,
                    "id": "9f65bc20-0",
                    "local": "mx2.improvmx.com",
                    "message": "Queued",
                    "server": "mail-pj1-f32.google.com",
                    "status": "QUEUED"
                },
                {
                    "code": 250,
                    "created": 1747030327000,
                    "id": "9f65bc20-1",
                    "local": "gmail-smtp-in.l.google.com",
                    "message": "Sent.",
                    "server": "mail12.mxa.infra.improvmx.com",
                    "status": "DELIVERED"
                }
            ],
            "forward": {
                "email": "[email protected]",
                "name": "Jared Dunn"
            },
            "hostname": "mail-pj1-f32.google.com",
            "id": "20250512061204.9f65bc20deab4f71bcedad1dfc513e9a",
            "messageId": "9f65bc20deab4f71bcedad1dfc513e9a",
            "recipient": {
                "email": "[email protected]",
                "name": null
            },
            "sender": {
                "email": "[email protected]",
                "name": "Laurie Bream"
            },
            "subject": "Re: Series A funding timeline",
            "transport": "smtp"
        }
    ],
    "success": true
}

SMTP Credentials

Add SMTP credentials to your domain to send emails from your domain. I.e. send from [email protected] instead of [email protected].

List credentials

GET /domains/:domain/credentials

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

Response:

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

Add credential

POST /domains/:domain/credentials

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"
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`username`	True	String	Local part of the mailbox (e.g. `bighead` for `[email protected]`).
`password`	True	String	SMTP credential password.

Response:

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

requires_new_mx_check is true on your first credential. First-time SMTP setup requires two new DKIM CNAMEs and a DMARC TXT entry in your DNS; sending is blocked until they're added.

Update credential

PUT /domains/:domain/credentials/:username

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"
  }'

Response:

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

Delete credential

DELETE /domains/:domain/credentials/:username

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

Response:

{
    "success": true
}

Send API

Send emails from your domain through the same infrastructure as SMTP credentials.

NOTE: Sending is a premium feature.

Send an email

POST /domains/:domain/emails/outbound

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/emails/outbound \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "from": "richard",
      "to": "[email protected]",
      "subject": "Hello from the API",
      "text": "This is a plain text email sent via the ImprovMX API.",
      "html": "Hello!
This is an HTML email sent via the ImprovMX API."
  }'

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`from`	String	True	Local part of the sender address (e.g. `richard` → `[email protected]`).
`to`	String or Array	True	Recipient(s). String or array of strings.
`subject`	String	True*	Email subject. *Optional when `template` provides one. Supports Mustache variables.
`text`	String	False	Plain text body. Required (along with or instead of `html`) when `template` is not used.
`html`	String	False	HTML body. Required (along with or instead of `text`) when `template` is not used.
`template`	String	False	Name of a saved template. Its `subject`, `html_body`, and `text_body` are rendered with `variables`. Request-level `text` / `html` are ignored; `subject` overrides the template's.
`variables`	Object	False	Mustache variable substitutions. Only used with `template`.
`cc`	String or Array	False	CC recipient(s). String or array of strings.
`bcc`	String or Array	False	BCC recipient(s). String or array of strings.
`reply_to`	String	False	Reply-To email address.
`attachments`	Array	False	Each object needs `filename` and `content` (base64). Optional: `content_type` (inferred from filename) and `content_id` for inline CID images (e.g. `<img src="cid:logo">`). Max 25 attachments, 10 MB total. Executable extensions (exe, bat, js, vbs, ps1, scr, etc.) are blocked.

Response:

{
    "message_id": "20250330190000.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "success": true
}

Use message_id to track delivery status.

Example: multiple recipients with CC and BCC

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/emails/outbound \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "from": "richard",
      "to": [
          "[email protected]",
          "[email protected]"
      ],
      "cc": [
          "[email protected]"
      ],
      "bcc": [
          "[email protected]"
      ],
      "reply_to": "[email protected]",
      "subject": "Team update",
      "text": "Here is the latest update.",
      "html": "Here is the latest update."
  }'

Example: sending with a template

Render a saved template with variables.

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/emails/outbound \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "from": "richard",
      "to": "[email protected]",
      "template": "welcome",
      "variables": {
          "first_name": "Gilfoyle",
          "company": "Pied Piper"
      }
  }'

Example: sending with attachments

Pass each attachment with base64 content. content_type is inferred from the filename if omitted.

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/emails/outbound \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "from": "richard",
      "to": "[email protected]",
      "subject": "Q4 Report",
      "text": "Please find the report attached.",
      "attachments": [
          {
              "filename": "report.pdf",
              "content": "JVBERi0xLjQg...",
              "content_type": "application/pdf"
          }
      ]
  }'

Example: inline image with content_id

Embed inline images via cid: references using content_id.

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/emails/outbound \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "richard",
    "to": "[email protected]",
    "subject": "Check out our new logo",
    "html": "<p>Here is our logo:</p><img src=\"cid:logo\">",
    "attachments": [
      {
        "filename": "logo.png",
        "content": "iVBORw0KGgo...",
        "content_type": "image/png",
        "content_id": "logo"
      }
    ]
  }'

Error responses

CODE	DESCRIPTION
400	Missing required fields - `from`, `to`, or `subject` is missing.
400	No body content - `text` or `html` is required.
400	Invalid email addresses - Invalid address in `to`, `cc`, `bcc`, or `reply_to`.
400	Invalid variables - `variables` must be a JSON object.
400	Invalid Mustache template - Malformed Mustache syntax in the template's subject or body.
400	Invalid attachment - Missing `filename` or `content`, invalid base64, invalid `content_type`, or `attachments` is not an array.
400	Blocked file type - Blocked extension (e.g. exe, bat, js, vbs, ps1, scr).
400	Attachment size limit - Over 10 MB total or more than 25 attachments.
403	Premium required - A premium plan is required to send emails via API.
403	Domain not configured for sending - The domain's DNS settings are not configured for sending. Visit `https://app.improvmx.com/domains/:domain/dns` to complete setup.
404	Domain not found - Not in your account.
404	Template not found - No `template` with that name on this domain.
429	Rate limited - Exceeded 10 requests/minute.

Get email status

GET /domains/:domain/emails/outbound/:message_id

Look up delivery status by message_id.

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

Response:

{
    "success": true,
    "message_id": "20250330190000.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "status": "delivered",
    "created_at": 1711828800000,
    "subject": "Hello from the API",
    "sender": "[email protected]",
    "recipient": "[email protected]",
    "events": [
        {
            "status": "QUEUED",
            "message": "Queued for delivery",
            "code": "250",
            "server": "api.improvmx.com",
            "created": 1711828800000
        },
        {
            "status": "DELIVERED",
            "message": "250 OK",
            "code": "250",
            "server": "mx.example.com",
            "created": 1711828810000
        }
    ]
}

The status field is one of:

STATUS	DESCRIPTION
`pending`	Queued for delivery.
`delivered`	Delivered to the recipient's mail server.
`bounced`	Delivery failed (hard or soft bounce).

Send API Templates

Save reusable templates per domain and reference them by name when sending. Subject and body support Mustache variables filled from the request's variables object.

Requires a premium plan. Up to 200 templates per domain.

Template object

{
    "name": "welcome",
    "description": "Welcome email for new signups",
    "subject": "Welcome, {{first_name}}!",
    "html_body": "<p>Hi {{first_name}}, welcome to {{company}}.</p>",
    "text_body": "Hi {{first_name}}, welcome to {{company}}.",
    "created_at": "2025-03-30T19:00:00Z",
    "updated_at": "2025-03-30T19:00:00Z"
}

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`name`	String	True	Unique within the domain. Lowercase letters, numbers, hyphens, underscores; must start with a letter or number. Max 250 chars.
`description`	String	False	Description (max 500 chars).
`subject`	String	False	Default subject (max 250 chars). Supports Mustache.
`html_body`	String	False	HTML body (max 100,000 chars). Supports Mustache.
`text_body`	String	False	Plain text body (max 100,000 chars). Supports Mustache.

List templates

GET /domains/:domain/templates

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

Returns summary fields (name, description, subject, created_at, updated_at) only. Fetch a single template to get its bodies.

{
    "success": true,
    "templates": [
        {
            "name": "welcome",
            "description": "Welcome email for new signups",
            "subject": "Welcome, {{first_name}}!",
            "created_at": "2025-03-30T19:00:00Z",
            "updated_at": "2025-03-30T19:00:00Z"
        }
    ]
}

Get template

GET /domains/:domain/templates/:name

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

Response:

{
    "success": true,
    "template": {
        "name": "welcome",
        "description": "Welcome email for new signups",
        "subject": "Welcome, {{first_name}}!",
        "html_body": "<p>Hi {{first_name}}, welcome to {{company}}.</p>",
        "text_body": "Hi {{first_name}}, welcome to {{company}}.",
        "created_at": "2025-03-30T19:00:00Z",
        "updated_at": "2025-03-30T19:00:00Z"
    }
}

Create template

POST /domains/:domain/templates

curl -X POST https://api.improvmx.com/v3/domains/piedpiper.com/templates \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "welcome",
      "description": "Welcome email for new signups",
      "subject": "Welcome, {{first_name}}!",
      "html_body": "Hi {{first_name}}, welcome to {{company}}.",
      "text_body": "Hi {{first_name}}, welcome to {{company}}."
  }'

Response:

{
    "success": true,
    "template": {
        "name": "welcome",
        "description": "Welcome email for new signups",
        "subject": "Welcome, {{first_name}}!",
        "html_body": "<p>Hi {{first_name}}, welcome to {{company}}.</p>",
        "text_body": "Hi {{first_name}}, welcome to {{company}}.",
        "created_at": "2025-03-30T19:00:00Z",
        "updated_at": "2025-03-30T19:00:00Z"
    }
}

Error responses

CODE	DESCRIPTION
400	Validation error - Missing `name`, invalid name format, field too long, or invalid Mustache syntax.
400	Template already exists - `name` is taken on this domain.
400	Limit reached - 200 templates per domain.
403	Premium required - Templates require a premium plan.
404	Domain not found - Not in your account.

Update template

PUT /domains/:domain/templates/:name

Only included fields are updated. Pass a new name to rename.

curl -X PUT https://api.improvmx.com/v3/domains/piedpiper.com/templates/welcome \
  -H "Authorization: Basic api:$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "subject": "Welcome to {{company}}, {{first_name}}!"
  }'

Response:

{
    "success": true,
    "template": {
        "name": "welcome",
        "description": "Welcome email for new signups",
        "subject": "Welcome to {{company}}, {{first_name}}!",
        "html_body": "<p>Hi {{first_name}}, welcome to {{company}}.</p>",
        "text_body": "Hi {{first_name}}, welcome to {{company}}.",
        "created_at": "2025-03-30T19:00:00Z",
        "updated_at": "2025-03-30T19:05:00Z"
    }
}

Error responses

CODE	DESCRIPTION
400	Validation error - Invalid name format, field too long, or invalid Mustache syntax.
400	Template already exists - New `name` is taken by another template.
404	Domain or template not found - Not in your account.

Delete template

DELETE /domains/:domain/templates/:name

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

Response:

{
    "success": true
}