How to migrate from Textmagic API v1 to API v2

Textmagic API v1 is being retired. This guide explains the two upcoming changes, how to keep your current integration working during the transition, and how to move to the Textmagic REST API v2.

Why move to API v2

Protecting your account and customer messages is the main reason for this change. Moving to API v2 reduces the risk of exposing your API credentials and gives you more control over access to each integration.

Sending an API password in a request URL puts your account at risk. URLs can be recorded in server logs and monitoring tools, even when the connection uses HTTPS. If someone gains access to a recorded password, they may be able to send messages at your expense or read incoming messages.

API v2 uses an API key sent in HTTP headers rather than in the URL. You can create a separate key for each application and revoke an individual key when access is no longer needed, without changing your account password or replacing the keys used by other applications.

If you already send your v1 password in the request body, you avoid the URL-related risk described above. You will still need to move to API v2 before May 1, 2027, when API v1 is switched off.

We understand that changing an established integration takes planning. You can use the temporary option below if you need more time for the full migration. If you need help with your setup, contact [email protected].

On this page

• Why move to API v2
• Temporary option: keep API v1 working until May 1, 2027
• How to migrate to API v2
• Step 1. Create an API v2 key
• Step 2. Change the URL and the authentication
• Step 3. Replace each v1 command
• Step 4. Choose callbacks or polling
• Step 5. Test, then retire the old password
• Official client libraries
• Checklist for your developer

Temporary option: keep API v1 working until May 1, 2027

Complete this update before February 1, 2027 if you cannot move to API v2 by then. From that date, API v1 will no longer accept passwords in request URLs, regardless of the HTTP method used.

You can keep using API v1 temporarily by changing all requests to POST and placing all parameters, including username and password, in the request body. Use Content-Type: application/x-www-form-urlencoded and send requests directly to https://www.textmagic.com/app/api, with no parameters in the URL.

This applies to all requests, including sending SMS and checking incoming messages, delivery statuses, and account balance. Commands, parameter names, and response formats stay the same.

1. Update every API v1 request to use POST with all parameters in the body. Remove the username and password from the URL completely.
2. Test all integrations that use the API v1 password, including any scheduled processes.
3. Once all integrations use this method, open API v1 settings, generate a new API v1 password, and update all integrations to use it. The old password stops working immediately, so coordinate the replacement across your systems to avoid failed requests.

If you already send your API password only in the POST body, no request changes are needed for this phase. If the password was previously sent in URLs, replace it once all integrations have been updated.

Always use HTTPS and keep passwords and API keys out of logs and source code. Sending credentials in the body or a header does not remove the need to protect them.

How to migrate to API v2

Follow the steps below to move your integration to API v2 before May 1, 2027. If you complete them before February 1, 2027, you do not need the temporary v1 update above. You can forward this guide to the developer who manages your integration.

Step 1. Create an API v2 key

Old API v1 passwords do not work with API v2. You need a new key:

1. Log in to Textmagic and open Settings → API → API v2 keys (direct link).
2. Click Add new API key.
3. Enter any name for your app (for example, “CRM integration”) and click Generate new key.
4. Copy the key and store it as a secret in your application settings.

Create a separate key for each application or server. Then you can switch one off without breaking the others.

Step 2. Change the URL and the authentication

Sending one SMS, before and after. The legacy URL example below is shown only for comparison; it will no longer work from February 1, 2027:

# API v1
GET https://www.textmagic.com/app/api?username=USERNAME&password=API_PASSWORD&cmd=send&phone=447860021130&text=Hello

# API v2
curl -X POST https://rest.textmagic.com/api/v2/messages \
  -H "X-TM-Username: USERNAME" \
  -H "X-TM-Key: API_V2_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": "447860021130", "text": "Hello"}'

Response (201 Created):

{"id": 49576009, "href": "/api/v2/messages/49576009", "type": "message",
 "sessionId": 34436600, "bulkId": null, "messageId": 49576009, "scheduleId": null}

Step 3. Replace each v1 command

Parameters of send

Responses are different

• Message IDs. v1 returned a map of phone number → message ID. In v2, a message to one number returns messageId. A message to several numbers returns sessionId; get the message IDs with GET /sessions/{id}/messages (docs).
• Delivery status is a letter, for example d delivered, f failed, j rejected. The full list is in Delivery status codes.
• Errors come as HTTP status codes with a JSON body. Check the status code first, not the body. See Response codes.
• Lists (GET /replies, GET /messages) are paged: up to 100 items per page (limit), with page and pageCount in the response.

Step 4. Choose callbacks or polling

If your integration calls cmd=receive or cmd=message_status every few seconds, consider switching to callbacks. This is optional; you can also keep polling with the v2 endpoints. Textmagic sends each incoming message and each final delivery status to your server as soon as it arrives, so you no longer need to poll.

1. Open Settings → API → API v2 settings.
2. In Callback URL, fill in For inbound messages and/or For delivery notifications.
3. Set Callback format to JSON if your server reads JSON.
4. Click Test, then save.

Your server must answer 200 OK. Details: incoming messages callback, delivery status callback.

If you keep polling, stay under 50 requests per second; above that the API returns 429 Too Many Requests (limits).

Step 5. Test, then retire the old password

1. Test every integration that uses your API v1 password. Send a test message through v2 and check that delivery statuses and replies reach your system. Also test any scheduled or bulk messages your integration uses.
2. Once all integrations have moved to v2 and passed testing, remove the v1 URL and password from your code and configuration.
3. Open Settings → API → API v1 (legacy) and click Generate new API password. This makes the old password, including any copies previously recorded in URLs or logs, stop working immediately. Do not put the new password into any integration.

Keep the v2 key out of URLs, logs and source code repositories. If a key leaks, delete it in Settings → API → API v2 keys and create a new one.

Official client libraries

Use the official libraries and code examples to help you connect your application to API v2. Choose your language for setup instructions:

• PHP
• Node.js
• Java
• C# / VB.NET
• C++
• Python
• Perl
• Ruby
• Go
• Delphi
• Bash

Checklist for your developer

• API v2 key created and stored as a secret.
• Base URL changed to https://rest.textmagic.com/api/v2.
• Credentials sent in X-TM-Username / X-TM-Key headers, not in the URL.
• Every cmd= call replaced (table in Step 3), send parameters renamed.
• Error handling reads HTTP status codes.
• Polling replaced with callbacks, or kept under the rate limit.
• Test message sent and tracked end to end.
• Old v1 password regenerated and removed from all configs.

Questions: [email protected]. Full API reference: docs.textmagic.com.