An API migration email has a specific job: help the person maintaining an integration make the required change before the old behaviour disappears. A clear subject line cannot compensate for an uncertain deadline or missing migration instructions.
The sequence below is a planning framework. The field names and scenarios are hypothetical; they do not announce a breaking change to Mergelay’s API.
Write down the compatibility contract first
Before drafting the email, get agreement on what changes, which versions are affected, how the old behaviour is handled during the transition and when it ends. Include a timezone for a time-sensitive cutover. If that date is still tentative, say so internally and resolve it before presenting it as a customer commitment.
A merged PR may rename a field, but the rollout could involve a compatibility layer, a version header or a period when both formats work. The announcement needs the actual migration contract, not just the code diff.
- Affected endpoint, event or SDK version.
- Old behaviour and supported replacement.
- Transition behaviour and confirmed cutover date.
- Test procedure, expected result and support route.
Find the people who can change the integration
The person paying the invoice may not maintain the integration. Use the technical contacts and account information your team is authorised to use. Where you have reliable usage evidence, use it to determine which accounts still depend on the old behaviour.
Be explicit about uncertainty. If you cannot identify affected usage, do not tell a recipient that their integration is definitely broken. Explain the condition that makes the notice relevant and give them a way to check.
This change affects integrations that read customer_id from the invoice response. Check the parser used by your integration. If it already reads customer.id, the field migration described here does not apply.
Give the email a stable migration page to point to
Keep the detailed before-and-after payloads, test instructions and known limitations on a maintained page. The email can then carry the essential action and deadline without becoming a long specification. The page should agree with the email on field names, scope and dates.
Have someone follow the instructions using a representative test integration. A code sample that looks plausible is not enough. If migration requires a particular SDK release or configuration change, put that prerequisite before the steps that depend on it.
Plan follow-up around readiness
Choose the lead time according to the work customers need to do and the commitments your team has made. There is no universal number of days that makes every API change reasonable. Review the timeline with the people responsible for the rollout and customer relationships.
The first notice should establish applicability, action, deadline and help. Later communication should reflect what you know: a reminder to an integration still using the old format is more useful than another identical broadcast to accounts that have already migrated.
If the cutover changes, update the migration page and tell affected recipients what changed. Do not silently edit the only record of the original deadline and assume everyone will revisit it.
Review the exact notice and track the migration
Before publication, compare the email and migration page against the release plan. Check the selected audience, destination, links, date and timezone. Keep a record of the approved wording so the team can establish what customers were told.
Measure the outcome that matters: whether affected integrations have moved to the supported behaviour. Delivery status and email engagement can help investigate communication problems, but neither proves migration completion.
Mergelay can help turn source Changes into drafts for review. The team still needs to establish the compatibility contract, verify the rollout and decide which customers need the notice. Those facts belong in the source material before a draft asks anyone to act.
Start with one meaningful change.
Bring your GitHub Changes into Mergelay and prepare an Update for review.
Start free