canonical: https://jentic.com/apis/improvmx.com/improvmx

# ImprovMX API

ImprovMX is an email forwarding service that lets you receive mail at a custom domain and route it to any inbox. The API exposes 29 endpoints covering domains, aliases, forwarding rules, SMTP credentials, account details, whitelabel domains, and email logs. Authentication uses HTTP Basic with the username 'API' and your API key as the password. The API is well suited to support agents and automation that provision domains, manage aliases in bulk, and audit forwarding activity.

## For AI agents

Manage ImprovMX domains, aliases, forwarding rules, SMTP credentials, and email logs programmatically. Useful for support agents and provisioning automation.

## Scope

Does not send transactional or marketing email at scale, manage mailboxes, or host inboxes - use for email forwarding, alias management, and forwarding logs only.

## Capabilities

- Add and verify a custom domain for email forwarding
- Create, update, and delete email aliases on a domain
- Bulk modify aliases in a single call for migrations
- Configure SMTP credentials for outbound sending
- Pull email logs to investigate delivery and forwarding events
- Check DNS configuration on a domain to confirm MX and SPF setup
- List whitelabel domains attached to the account

## Use cases

### Domain and Alias Provisioning

Onboarding flows for new tenants can use the ImprovMX API to add a domain, create the standard set of aliases, and verify that DNS is correctly configured. The /domains and `/domains/{domain}/aliases` endpoints make this a few API calls rather than dashboard clicks.

Example prompt: Add the domain example.com, create aliases support@ and billing@ both forwarding to ops@example.com, and run the DNS check.

### Bulk Alias Migration

When migrating from another forwarding provider, POST `/domains/{domain}/aliases/bulk` allows aliases to be modified in one batch instead of one call per row. The bulk endpoint reduces migration time and request count for large alias sets.

Example prompt: Bulk update aliases on example.com from a CSV containing 200 rows of alias-to-destination mappings.

### Email Log Investigation

Support agents resolving missing-mail tickets can fetch ImprovMX email logs to confirm whether mail arrived, was forwarded, bounced, or was held for spam. Logs include timestamps, source, destination, and outcome to drive a fast triage.

Example prompt: Fetch email logs for domain example.com from the past 24 hours and report any entries with status other than 'forwarded'.

### Jentic Email Operations Agent

Through Jentic, an agent can manage ImprovMX domains and aliases from a chat surface. It searches by intent, loads the schema, and executes the right ImprovMX endpoint without context-switching to the dashboard, while Jentic isolates the API key.

Example prompt: Search Jentic for 'create an alias on a domain', load the schema, and create alias help@example.com forwarding to ops@example.com.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/domains` | List forwarding domains |
| POST | `/domains` | Add a new domain |
| GET | `/domains/{domain}/check` | Check domain DNS configuration |
| POST | `/domains/{domain}/aliases` | Add an alias to a domain |
| POST | `/domains/{domain}/aliases/bulk` | Bulk modify aliases |
| DELETE | `/domains/{domain}/aliases/aliases-all` | Delete all aliases on a domain |
| GET | `/domains/{domain}/rules` | List forwarding rules |

## Key resources

- **Domains** — Add, retrieve, update, delete, and DNS-check forwarding domains
- **Aliases** — Create, list, update, delete, and bulk-modify aliases on a domain
- **Rules** — Manage forwarding rules attached to a domain
- **Logs** — Pull email forwarding logs for delivery and audit
- **SMTP Credentials** — Manage SMTP credentials used for outbound sending
- **Account** — Retrieve account details and whitelabel domain configuration

## Why Jentic

- **Setup:** Wiring ImprovMX by hand means setting up HTTP Basic auth with the literal username 'API' plus your API key and encoding it into every Authorization header yourself. Through Jentic you install once, import ImprovMX from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** ImprovMX puts the domain in the URL path (`/domains/{domain}/...`), so a rule can pin your agent to one domain: it can manage aliases and read forwarding rules for that domain and nothing else. You choose the operations it may call, so destructive ones like deleting all aliases are not included unless you add them.
- **Credential handling:** Your ImprovMX Basic auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an email alias' or 'check domain DNS', and Jentic returns the matching ImprovMX operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Postmark Server API** — Transactional email sending service with templates and delivery analytics
- **SendGrid Domain Authentication** — Configure SPF, DKIM, and DMARC for sending domains
- **Cloudflare** — DNS management often paired with ImprovMX for MX and SPF records

## FAQ

### What authentication does the ImprovMX API use?

ImprovMX uses HTTP Basic authentication with the username 'API' and your API key as the password. Through Jentic, the credentials are stored in the encrypted vault and the agent receives a scoped Jentic token, so the raw API key never enters the agent context.

### Can I bulk update aliases on a domain?

Yes. POST `/domains/{domain}/aliases/bulk` modifies many aliases in one call, which is the right pattern for migrations and large alias sets. There is also DELETE `/domains/{domain}/aliases/aliases-all` to clear every alias on a domain at once.

### What are the rate limits for the ImprovMX API?

ImprovMX enforces per-account rate limits that depend on plan tier; the OpenAPI spec does not list hard numbers. Bulk endpoints reduce the request count for large mutations, so they should be preferred over per-alias loops.

### How do I create an alias through Jentic?

Search Jentic for 'create an alias on a domain' to find the operation backed by POST `/domains/{domain}/aliases.` Load the schema, pass the domain, alias, and forwarding destination, and execute. Jentic injects the Basic auth credentials at runtime.

### How do I confirm DNS is set up correctly for a domain?

Call GET `/domains/{domain}/check.` The response confirms whether the MX and SPF records are aligned with ImprovMX's expected configuration, which is the fastest way to debug a domain that is not forwarding mail.

### Can I retrieve email logs for a domain?

Yes. The Logs endpoints under `/domains/{domain}` return forwarding events including timestamps, source, destination, and outcome, which support agents use to investigate missing or delayed mail.

### Can I limit what my agent is allowed to do with the ImprovMX API?

Yes. Because you run Jentic One yourself, your own rules decide which ImprovMX operations and credentials the agent can use. Since ImprovMX puts the domain in the URL path (`/domains/{domain}/...`), you can pin the agent to a single domain so it manages aliases and reads forwarding rules for that domain and nothing else. You also choose the exact operations it may call, so destructive ones like DELETE `/domains/{domain}/aliases/aliases-all` are excluded unless you add them.