Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 2.152s · 50MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.2s · import 1.962s · 50MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Vonage
✓ from vonage import Vonage
SmsMessage
✓ from vonage_sms import SmsMessage
SmsResponse
✓ from vonage_sms import SmsResponse
Client
✓ from vonage import Client
✗ import vonage.Client
The primary client class for the Vonage SDK is `Client`, which is imported directly from `vonage`.
This quickstart demonstrates how to send an SMS message using the `vonage` client, which integrates the `vonage-sms` package. It uses environment variables for API credentials and phone numbers, and includes basic error handling. Phone numbers must be in E.164 format.
import os
from vonage import Vonage
from vonage_sms import SmsMessage
# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set as environment variables
api_key = os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY')
api_secret = os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET')
if api_key == 'YOUR_API_KEY' or api_secret == 'YOUR_API_SECRET':
print("Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables.")
else:
client = Vonage(key=api_key, secret=api_secret)
# Replace with your Vonage virtual number (sender) and recipient number
# Numbers must be in E.164 format (e.g., '12345678900')
from_number = os.environ.get('VONAGE_NUMBER', 'YOUR_VONAGE_NUMBER')
to_number = os.environ.get('RECIPIENT_NUMBER', 'YOUR_RECIPIENT_NUMBER')
if from_number == 'YOUR_VONAGE_NUMBER' or to_number == 'YOUR_RECIPIENT_NUMBER':
print("Please set VONAGE_NUMBER and RECIPIENT_NUMBER environment variables.")
else:
message = SmsMessage(
to=to_number,
from_=from_number,
text='Hello from the Vonage Python SDK!'
)
try:
response = client.sms.send(message)
if response.messages[0].status == '0':
print(f"Message sent successfully to {to_number}.")
else:
print(f"Message failed with error: {response.messages[0].error_text} (status: {response.messages[0].status})")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `vonage-sms` package is part of a monorepo. It's recommended to install the main `vonage` package (e.g., `pip install vonage`) rather than `vonage-sms` directly, as the `vonage` package provides the primary client and manages dependencies.fixEnsure `pip install vonage` is used. Most functionality is accessed via `vonage.Vonage().sms`.
affects: <4.0.0 of vonage SDK
gotchaPhone numbers must strictly adhere to the E.164 format (e.g., '12345678900' for +1 (234) 567-8900). Leading '+' or '00' should not be used; start directly with the country code.fixFormat all phone numbers to E.164. Consult Vonage documentation for country-specific formatting details and restrictions.
affects: All versions
gotchaIn North America (US/Canada), only numerical Sender IDs are typically allowed, and application-to-person (A2P) messages often require a registered 10DLC brand and campaign, or a Toll-Free Number/Short Code. Alphanumeric Sender IDs may be filtered or rejected.fixUse a Vonage virtual number, toll-free number, or short code as the `from` address. For US A2P messaging, register your brand and campaign for 10DLC compliance.
affects: All versions
gotchaDemo or trial accounts have limitations, such as sending only to whitelisted destination numbers. Messages may also be prepended with '[FREE SMS DEMO, TEST MESSAGE]'.fixTop up your Vonage account to remove demo restrictions and enable sending to any number.
affects: All versions for trial accounts
gotchaSMS messages have length limits (e.g., 160 GSM characters or 70 Unicode characters per segment). Longer messages are concatenated, which can sometimes split URLs or incur additional costs.fixKeep messages concise. Be aware of character encoding (GSM vs. Unicode) as it affects the character limit per segment. Check country-specific guidelines for maximum message length.
affects: All versions
Errors
Common errors & fixes
Message failed with error: Missing Parameters (status: 2)
One of the required parameters (`from`, `to`, `api_key`, `api_secret`, or `text`) was missing or empty in the API request.
fixDouble-check that all required fields (`to`, `from_`, `text`) are provided to the `SmsMessage` object and that your `api_key` and `api_secret` are correctly configured in the `Vonage` client.
Message failed with error: Invalid Credentials (status: 4)
The provided API key and/or secret are incorrect, invalid, or disabled for your Vonage account.
fixVerify your API Key and API Secret in your Vonage Dashboard. Ensure no typos and that the credentials are for the correct account.
Message failed with error: Non-Whitelisted Destination (status: 29)
Your Vonage account is in demo mode and the recipient number is not on your whitelisted destination list.
fixEither add the recipient number to your whitelisted destinations in the Vonage Dashboard or top up your account to move out of demo mode.
Message failed with error: Invalid Sender Address (status: 15)
You are using an unauthorized sender ID in the 'from' field, especially common in North America where a Vonage long virtual number or short code is required.
fixUse a Vonage virtual number that you own as the 'from' number. For North American traffic, ensure it's a registered 10DLC number, Toll-Free Number, or Short Code.
Message failed with error: Partner Quota Violation (status: 9)
You do not have sufficient credit on your Vonage account to send the message.
fixLog in to your Vonage Dashboard and top up your account balance.
Upgrade
Version history
1.2.0latest on PyPI · released Apr 22, 2026
Audit
Dependencies
pythonrequiredRequired for execution.