Before you start
- An API connection created in the web panel (app.grupotecnophone.com), with its Bearer Token for sandbox or production.
- Your server’s public IP registered as authorized for that token.
- A User-Agent header that identifies your application, for example
MyCompany/1.0. - Python 3.8 or later. The example uses the library
requests(pip install requests); the official documentation also includes an example that uses only the standard library.
Store the token in an environment variable (in these examples, GTP_SMS_TOKEN) and never include it in the code of a mobile app or website: API calls must always come from your backend, from an authorized IP.
Send an SMS with Python
This function sends an SMS and returns the API response, or raises an exception with the error code:
import os
import requests
ENDPOINT = "https://api.grupotecnophone.com/prod/v1/sms/send"
TOKEN = os.environ["GTP_SMS_TOKEN"]
def send_sms(to: str, body: str) -> dict:
resp = requests.post(
ENDPOINT,
json={"to": to, "body": body},
headers={
"Authorization": f"Bearer {TOKEN}",
"User-Agent": "MyCompany/1.0",
},
timeout=30,
)
try:
data = resp.json()
except ValueError:
data = {}
if resp.status_code == 200 and data.get("status") == "success":
return data # sid, encoding, num_chars, num_segments
error = data.get("error") or {}
code = error.get("code", f"HTTP_{resp.status_code}")
raise RuntimeError(f"{code}: {error.get('message', resp.text)}")
if __name__ == "__main__":
result = send_sms("+525512345678", "Your verification code is 482913. It expires in 5 minutes.")
print(result["sid"], result["num_segments"])API response
If the message was accepted, the API responds with HTTP 200 and a JSON body like this:
{
"sid": "sms_20261012143201_39bdafbd",
"status": "success",
"to": "+525512345678",
"body": "Your verification code is 482913. It expires in 5 minutes.",
"encoding": "GSM7",
"num_chars": 56,
"num_segments": 1,
"error": null
}Store the sid: it is the identifier you will use to reconcile the message’s delivery report. The num_segments field indicates how many segments will be billed; see how segments are calculated.
Send SMS to multiple recipients with Python
To send bulk SMS from Python, just loop through your list and call the same send_sms function from the previous example. Store the sid of each send and set aside numbers with errors to review them later.
import time
recipients = ["+525512345678", "+525598765432", "+523312345678"]
message = "Your order 1234 is on its way. Thank you for your purchase."
sent, failed = [], []
for number in recipients:
try:
r = send_sms(number, message)
sent.append((number, r["sid"]))
except RuntimeError as e:
failed.append((number, str(e)))
time.sleep(0.1) # moderate pace for large lists
print(f"{len(sent)} sent, {len(failed)} failed")For lists of thousands of numbers, process in batches and retry only temporary errors. If you prefer not to code, you can also send bulk SMS from Excel or CSV in the platform panel.
Send an OTP code with Python
A very common case is sending a verification code. Generate the code with the secrets module (not with random), send it by SMS and store only its hash with an expiry date.
import secrets
def enviar_otp(number: str) -> str:
otp = f"{secrets.randbelow(10**6):06d}" # 6 digits from a secure generator
send_sms(number, f"Your verification code is {otp}. It expires in 5 minutes. Do not share it.")
return otp # store it hashed with an expiry date, never in plain textSee how to design the complete flow, expiry times and retries in our guide to SMS OTP authentication.
Common errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | ENCRYPTION_REQUIRED | The connection requires to and body to be encrypted with RSA-OAEP |
| 400 | ENCRYPTION_NOT_ALLOWED | The connection operates in plain text and encrypted content was received |
| 400 | INPUT_PHONE_BLACKLISTED | The destination number is on the blacklist |
| 400 | INSUFFICIENT_BALANCE | Insufficient balance for the send |
| 401 | — | Missing or invalid token |
| 403 | — | The source IP is not authorized for the token |
| 500 | — | Unexpected internal error |
On 400 errors the response includes an error object with code, code_num and message.
Test in sandbox
Change the endpoint to https://api.grupotecnophone.com/test/v1/sms/send and use the sandbox token. That environment validates the token, IP, payload and encryption with the same logic as production, but does not send real SMS.
Best practices
- Set a timeout and log each response with its
sid. - After a network error with no response, do not resend blindly: check first so you don’t duplicate the message to the user.
- Retry only 500 errors, with progressive backoff and a maximum number of attempts.
- Queue bulk sends instead of sending them within a web request cycle.
- If the content is sensitive, enable connection encryption; the API documentation includes an RSA encryption example in PHP without external libraries.
See also the SMS API for Mexico, the SMPP connection and the guides for PHP, Laravel, Node.js and Java. If you need test credentials, contact us.
