API deprecation email templates, from announcement to retirement
A deprecation date nobody is reminded about is a date nobody remembers. These five emails take a client from the announcement to the day after retirement. Copy them, replace the bracketed parts, and send each one only to the clients still calling the old version.
Every email follows the same rule: say what is changing, by when, and exactly what the reader has to do, in the first three lines. The engineer who reads it may not have built the integration.
1. The announcement
Send when you deprecate the version, at least as far ahead as your policy promises.
Subject: [API name] v1 will be retired on [date]
Hi [name],
[API name] v1 will stop working on [date]. Your integration, [client name],
called it [N] times in the last 30 days.
What to do: move these calls to v2 before [date].
- [GET /v1/invoices] → [GET /v2/invoices]
- [POST /v1/charges] → [POST /v2/payments]
The migration guide covers each change: [migration guide URL]
Why: [one sentence, e.g. "v2 supports multi-currency invoices, and we can't
add that to v1 without breaking it."]
If you need more time, reply to this email before [date].
[Your name]
[Team]2. Thirty days out
Subject: 30 days until [API name] v1 is retired
Hi [name],
[API name] v1 will be retired on [date], 30 days from today. [Client name]
is still calling it: [N] calls in the last 7 days, most recently [time].
These are the calls still on v1:
- [GET /v1/invoices] ([N] calls) → [GET /v2/invoices]
Migration guide: [URL]
Reply if anything is blocking you. We'd rather hear it now than on [date].3. Seven days out
Subject: Action needed: [API name] v1 stops working on [date]
Hi [name],
In 7 days, on [date], requests from [client name] to [API name] v1 will start
failing with 410 Gone. You made [N] v1 calls yesterday.
To keep working, move [GET /v1/invoices] to [GET /v2/invoices]: [URL]
If you can't migrate by [date], reply today and we'll talk about options.4. One day out
Subject: Tomorrow: [API name] v1 is retired
Hi [name],
[API name] v1 will be retired tomorrow, [date], at [time and time zone].
[Client name] called it [N] times in the last 24 hours, so this will affect you.
Migration guide: [URL]
Contact: [name, email, phone]5. The day after
Send only if the client kept calling after the date.
Subject: [API name] v1 has been retired
Hi [name],
[API name] v1 was retired on [date]. Since then, [client name] has made [N]
requests to it, and each one has returned 410 Gone.
To restore service, move to v2: [URL]
We're here to help: [contact].Getting them read
- Send to the owner, not the account. Billing contacts forward these late, or not at all. Keep a technical contact for every credential you issue.
- Include their own numbers. "You called this 4,200 times yesterday" gets action. "Some customers still use v1" doesn't.
- Stop sending once they've moved. A reminder to a client that already migrated teaches them to ignore the next one.
- Back it up in the response. Emails get lost. The Deprecation and Sunset headers reach whoever is running the code.
To fill in the "[N] calls" lines, you need usage by client. See how to find which clients still call an old API version.
Where EndPointBlank fits
EndPointBlank sends the reminders for you. Set a retirement date on a deprecated version and consumers are reminded 30, 7 and 1 day out, by email, Slack or Teams. The same record shows which clients are still calling it, so you know whose number to fill in for the personal follow-up.