{"id":15023,"library":"vonage-sms","title":"Vonage SMS Package","description":"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.","status":"active","version":"1.1.6","language":"en","source_language":"en","source_url":"https://github.com/Vonage/vonage-python-sdk","tags":["SMS","messaging","Vonage","Nexmo","telecom"],"install":[{"cmd":"pip install vonage","lang":"bash","label":"Recommended: Install the main Vonage Python SDK"},{"cmd":"pip install vonage-sms","lang":"bash","label":"Direct installation (usually pulled by 'vonage' SDK)"}],"dependencies":[{"reason":"Required for execution.","package":"python","optional":false}],"imports":[{"symbol":"Vonage","correct":"from vonage import Vonage"},{"symbol":"SmsMessage","correct":"from vonage_sms import SmsMessage"},{"symbol":"SmsResponse","correct":"from vonage_sms import SmsResponse"},{"note":"The primary client class for the Vonage SDK is `Client`, which is imported directly from `vonage`.","wrong":"import vonage.Client","symbol":"Client","correct":"from vonage import Client"}],"quickstart":{"code":"import os\nfrom vonage import Vonage\nfrom vonage_sms import SmsMessage\n\n# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set as environment variables\napi_key = os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY')\napi_secret = os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET')\n\nif api_key == 'YOUR_API_KEY' or api_secret == 'YOUR_API_SECRET':\n    print(\"Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables.\")\nelse:\n    client = Vonage(key=api_key, secret=api_secret)\n\n    # Replace with your Vonage virtual number (sender) and recipient number\n    # Numbers must be in E.164 format (e.g., '12345678900')\n    from_number = os.environ.get('VONAGE_NUMBER', 'YOUR_VONAGE_NUMBER')\n    to_number = os.environ.get('RECIPIENT_NUMBER', 'YOUR_RECIPIENT_NUMBER')\n\n    if from_number == 'YOUR_VONAGE_NUMBER' or to_number == 'YOUR_RECIPIENT_NUMBER':\n        print(\"Please set VONAGE_NUMBER and RECIPIENT_NUMBER environment variables.\")\n    else:\n        message = SmsMessage(\n            to=to_number,\n            from_=from_number,\n            text='Hello from the Vonage Python SDK!'\n        )\n\n        try:\n            response = client.sms.send(message)\n            if response.messages[0].status == '0':\n                print(f\"Message sent successfully to {to_number}.\")\n            else:\n                print(f\"Message failed with error: {response.messages[0].error_text} (status: {response.messages[0].status})\")\n        except Exception as e:\n            print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `pip install vonage` is used. Most functionality is accessed via `vonage.Vonage().sms`.","message":"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.","severity":"breaking","affected_versions":"<4.0.0 of vonage SDK"},{"fix":"Format all phone numbers to E.164. Consult Vonage documentation for country-specific formatting details and restrictions.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Top up your Vonage account to remove demo restrictions and enable sending to any number.","message":"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]'.","severity":"gotcha","affected_versions":"All versions for trial accounts"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"One of the required parameters (`from`, `to`, `api_key`, `api_secret`, or `text`) was missing or empty in the API request.","error":"Message failed with error: Missing Parameters (status: 2)"},{"fix":"Verify your API Key and API Secret in your Vonage Dashboard. Ensure no typos and that the credentials are for the correct account.","cause":"The provided API key and/or secret are incorrect, invalid, or disabled for your Vonage account.","error":"Message failed with error: Invalid Credentials (status: 4)"},{"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.","cause":"Your Vonage account is in demo mode and the recipient number is not on your whitelisted destination list.","error":"Message failed with error: Non-Whitelisted Destination (status: 29)"},{"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.","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.","error":"Message failed with error: Invalid Sender Address (status: 15)"},{"fix":"Log in to your Vonage Dashboard and top up your account balance.","cause":"You do not have sufficient credit on your Vonage account to send the message.","error":"Message failed with error: Partner Quota Violation (status: 9)"}],"ecosystem":"pypi"}