Announcing the v4 API

Updates

Version 4 of our API is out today. v3 has been around since April 2020 and six years of adding endpoints one at a time has left it in a sorry state. v4 does the same things, just consistently.

v3 is not deprecated. It keeps running and we keep supporting it, so there's no rush to move anything.

A Sampling of What Changed

  • Timestamps are ISO 8601 strings. You get "created_at": "2026-08-12T12:19:09Z" for all objects, which replaces the Unix millisecond number you previously had to convert.
  • Field names are snake_case throughout. No more mixture of camelCase.
  • Aliases are identified by id, so /aliases/11 rather than /aliases/richard. Renaming an alias no longer changes its URL.
  • Verifying a domain is now POST /domains/:domain/verify. In v3 it was GET /check, which was always a bit off for something that writes.
  • Lists paginate the same way everywhere, with limit and next_cursor.
  • Errors always come back with the same two keys. message is a string you can put in front of a user, and errors is a map of field to problems, empty when there's nothing field-specific to report.
  • The success field is gone. The status code already covered it.

Log search

The bigger change is logs search. In v3, GET /logs/search took your keyword and ran a regex against several unindexed fields and ORed the results. It was fine on a small domain and painful on a large one, and we had got into the habit of telling people to avoid it.

In v4 the same endpoint runs against a search index. It comes back in milliseconds and stays that way as your logs pile up. It tolerates typos, so searching for gavni@hooli.com still finds Gavin. Results are ranked by relevance by default, or you can sort by date. And the filters stack, so a keyword, a status, a transport and a time window all narrow the same query: 

curl -X GET https://api.improvmx.com/v4/domains/piedpiper.com/logs/search \
  -u "api:$API_KEY" -G \
  --data-urlencode "query=series a" \
  --data-urlencode "status=SOFT-BOUNCE,HARD-BOUNCE" \
  --data-urlencode "after=2026-08-01T00:00:00Z"

That's every bounced email mentioning the Series A since the start of August in one request. Your dashboard logs use the same endpoint, so search in the app got quicker as well.

Two smaller additions while we were in there. GET /domains/:domain/logs/:id returns a single email with its full delivery timeline, and /logs/count returns a total when a total is all you need.

Getting started

Point your base URL at v4 and read the reference. Your existing API key works as-is, and the docs have a v3/v4 toggle on every section if you want to compare an endpoint before you switch it over.

If you find something that's missing, or worse than it was in v3, let us know.

Thanks,
Matthew Tse
Owner and CEO @ ImprovMX

Matthew Tse

Matthew Tse

Owner and CEO of ImprovMX