Vonage SMS Package

1.1.6 · active · verified Thu Apr 16

The `vonage-sms` package provides Python access to Vonage's SMS API, enabling sending and receiving text messages globally. It is designed to be used as part of the main `vonage` Python SDK. The current version is 1.1.6, with updates typically aligned with the broader Vonage Python SDK releases.

Common errors

```
Message failed with error: Missing Parameters (status: 2)
```
cause One of the required parameters (`from`, `to`, `api_key`, `api_secret`, or `text`) was missing or empty in the API request.

fix Double-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)
```
cause The provided API key and/or secret are incorrect, invalid, or disabled for your Vonage account.

fix Verify 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)
```
cause Your Vonage account is in demo mode and the recipient number is not on your whitelisted destination list.

fix Either 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)
```
cause 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.

fix Use 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)
```
cause You do not have sufficient credit on your Vonage account to send the message.

fix Log in to your Vonage Dashboard and top up your account balance.

Warnings

breaking The `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.
Fix: Ensure `pip install vonage` is used. Most functionality is accessed via `vonage.Vonage().sms`.
gotcha Phone 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.
Fix: Format all phone numbers to E.164. Consult Vonage documentation for country-specific formatting details and restrictions.
gotcha In 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.
Fix: Use 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.
gotcha Demo or trial accounts have limitations, such as sending only to whitelisted destination numbers. Messages may also be prepended with '[FREE SMS DEMO, TEST MESSAGE]'.
Fix: Top up your Vonage account to remove demo restrictions and enable sending to any number.
gotcha SMS 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.
Fix: Keep 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.

Install

pip install vonage Recommended: Install the main Vonage Python SDK
pip install vonage-sms Direct installation (usually pulled by 'vonage' SDK)

Imports

Vonage
```
from vonage import Vonage
```
SmsMessage
```
from vonage_sms import SmsMessage
```
SmsResponse
```
from vonage_sms import SmsResponse
```
Client
wrong:
```
import vonage.Client
```
correct:
```
from vonage import Client
```
The primary client class for the Vonage SDK is `Client`, which is imported directly from `vonage`.

Quickstart

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}")

view raw JSON →