Migrating from POST /v1/messages

POST /v1/messages is deprecated. It keeps working until its sunset, 15 April 2027, and may be removed after that date. Its replacement is POST /v1/sms/messages.

What changes

Only the path. The replacement takes the same body and headers and gives the same responses, statuses and errors.

POST /v1/sms/messages HTTP/1.1Host: api.messaging.500calls.comAuthorization: Bearer 500c_live_…Content-Type: application/jsonIdempotency-Key: order-78123-otp{"to": "08031234567", "from": "ACME", "body": "Your ACME code is 482913. It expires in 5 minutes."}

Retries during the move

Both paths share their idempotency keys. A request sent to one path and retried on the other with the same Idempotency-Key and body gets the first response back, with Idempotent-Replayed: true, and sends nothing twice. You can switch paths in the middle of a retry.

How to tell if you still call it

Responses from POST /v1/messages carry these headers, errors included:

Deprecation: trueSunset: Thu, 15 Apr 2027 00:00:00 GMTLink: <https://docs.messaging.500calls.com/api/migrations/send-endpoint>; rel="deprecation"

Only a 413 or a 415 comes without them, because the request is refused before it reaches the endpoint.

Search your code for POST requests to /v1/messages, or log every response that has a Deprecation header. Reading messages with GET /v1/messages and cancelling one with POST /v1/messages/{id}/cancel are not affected.

Steps

1. Change the path from /v1/messages to /v1/sms/messages wherever you send.
2. Deploy. Nothing else changes, and retries already in flight still work.
3. Check that no response carries a Deprecation header any more.

After the sunset

After 15 April 2027 the old path may be removed. A send to it then answers 404 not_found and sends nothing. The changelog will record the removal.