The SMS Connexion API Python library provides convenient access to the SMS API of SMS.CX from applications written in Python language.
Using this library you can:
For more information, please visit https://sms.cx
Content:
Python >=3.6
Install the python package using:
pip install smscx_client
(you may need to run pip with root permission: sudo pip install smscx_client)
Then import the package:
import smscx_client
Install via Setuptools.
python setup.py install --user
(or sudo python setup.py install to install the package for all users)
Then import the package:
import smscx_client
To use the library you must authenticate. SMS.CX PHP Library supports the authentication methods supported by the SMS Connexion API:
To create a new API Key go to SMS.CX Account > HTTP API > API Keys and click on New API Key.
Copy the API Key and use it in this client library.
Access tokens are used by applications to make API requests.
To create a new application go to SMS.CX Account > HTTP API > Applications and click on New Application.
When you have the Application ID and Application Secret, you can use them to request an access token that you can use to make API calls.
Copy the APPLICATION_ID and APPLICATION_SECRET and use them to request an access token:
import time
import smscx_client
from smscx_client.api import oauth_api
from smscx_client.model.oauth_token_response import OauthTokenResponse
from pprint import pprint
configuration = smscx_client.Configuration(
username = "YOUR_APPLICATION_ID",
password = "YOUR_APPLICATION_SECRET"
)
# Create an instance of the API class
api_instance = oauth_api.OauthApi(
smscx_client.ApiClient(configuration)
)
# A list of space-delimited, case-sensitive strings
# If left empty or ommited, the issued access token will be granted with all scopes (full privileges) (optional)
scope = "sms groups templates numbers shortlinks attachments"
try:
# Get access token
api_response = api_instance.get_access_token(scope=scope)
pprint(api_response)
access_token = api_response.access_token
expires_in = api_response.expires_in
except smscx_client.InvalidRequestException as e:
# Code for invalid request # noqa: E501
except smscx_client.InvalidCredentialsException as e:
# Code for invalid credentials # noqa: E501
except smscx_client.InvalidScopeException as e:
# Code for invalid scope # noqa: E501
except smscx_client.ApiException as e:
print("Exception when calling OauthApi->get_access_token: %s\n" % e)
error_response = json.loads(e.body)
error_type = error_response['error']['type']
error_code = error_response['error']['code']
error_msg = error_response['error']['message']
http_code = e.status
Access tokens provide three main security benefits over using an API Key:
The library needs to be configured with your account's Application ID & secret or API Key which are available in your SMS.CX Dashboard.
The following example will send SMS to a single phone number:
import time
import smscx_client
from smscx_client.api import sms_api
from smscx_client.model.send_sms_message_request import SendSmsMessageRequest
from smscx_client.model.send_sms_message_response import SendSmsMessageResponse
from pprint import pprint
configuration = smscx_client.Configuration(
# Use authentication via API Key
api_key = "YOUR_API_KEY",
# Uncomment to use authentication via Access Token
# access_token = "YOUR_ACCESS_TOKEN",
)
# Create an instance of the API class
api_instance = sms_api.SmsApi(
smscx_client.ApiClient(configuration)
)
send_sms_message_request = SendSmsMessageRequest(
to=["+31612469xxx"],
_from = "InfoText",
text = "Your confirmation code is 15997",
)
try:
# Send single SMS
api_response = api_instance.send_sms(send_sms_message_request)
pprint(api_response)
# api_response.info.total_cost
for item in api_response.data:
# item.msg_id
except smscx_client.NoCoverageException as e:
# Code for No coverage
except smscx_client.InvalidRequestException as e:
# Code for invalid request
except smscx_client.InvalidPhoneNumberException as e:
# Code for invalid phone number
except smscx_client.InsufficientBalanceException as e:
# Code for insufficient balance
except smscx_client.ApiException as e:
print("Exception when calling SmsApi->send_sms: %s\n" % e)
error_response = json.loads(e.body)
error_response = json.loads(e.body)
error_type = error_response['error']['type']
error_code = error_response['error']['code']
error_msg = error_response['error']['message']
http_code = e.status
import time
import smscx_client
from smscx_client.api import sms_api
from smscx_client.model.send_sms_message_request import SendSmsMessageRequest
from smscx_client.model.send_sms_message_response import SendSmsMessageResponse
from pprint import pprint
configuration = smscx_client.Configuration(
# Use authentication via API Key
api_key = "YOUR_API_KEY",
# Uncomment to use authentication via Access Token
# access_token = "YOUR_ACCESS_TOKEN",
)
# Create an instance of the API class
api_instance = sms_api.SmsApi(
smscx_client.ApiClient(configuration)
)
send_sms_message_request = SendSmsMessageRequest(
to=[
"+31612469xxx",
"+4474005085xx",
"+49151238353xx",
"+417811126xx",
"+3519123350xx",
"+4206016090xx",
"+359483059xx",
"+336127904xx",
"+436645595xx",
"+3519121385xx",
"+3069125917xx",
],
_from="InfoText",
text="Redeem this voucher and you will get 30% discount off all Summer Fashion {{optoutLink}}",
idempotency_id="bf325375-e030-fccb-a009-17317c574773",
transliteration=Transliteration(
alphabet="NONE",
remove_emojis=False,
),
)
try:
# Send SMS
api_response = api_instance.send_sms(send_sms_message_request)
pprint(api_response)
# api_response.info.total_cost
for item in api_response.data:
# item.msg_id
except smscx_client.NoCoverageException as e:
# Code for No coverage
except smscx_client.InvalidRequestException as e:
# Code for invalid request
except smscx_client.InvalidPhoneNumberException as e:
# Code for invalid phone number
except smscx_client.InsufficientBalanceException as e:
# Code for insufficient balance
except smscx_client.ApiException as e:
print("Exception when calling SmsApi->send_sms: %s\n" % e)
error_response = json.loads(e.body)
error_type = error_response['error']['type']
error_code = error_response['error']['code']
error_msg = error_response['error']['message']
http_code = e.status
With this client library, you don’t need to check for non-200 HTTP responses. The library translates them as exceptions.
In some specific rare cases you may need to analyze the Error object for type and code properties.
To handle errors, use these two techniques:
The SMS.CX Python library raises an exception for every error type. It is recommended to catch and handle exceptions.
To catch an exception, use Python’s try/except syntax. SMS Connexion provides many exception classes you can catch. Each one represents a different kind of error. When you catch an exception, you can use its class to choose a response.
DuplicateIdException - A resource with the same ID already existDuplicateValueException - You are trying to create/update a resource that must be unique (eg. originators, group name, shortlinks, template name)InsufficientScopeException - Your application does not have the privilege to access a resourceInvalidCredentialsException - Unable to authenticate you based on the information provided.InvalidRequestException - The parameters provided were invalidInvalidScopeException - The scope requested does not existRateLimitExcedeedException - You made too many API calls in short period of time.ResourceNotFoundException - The ID of the requested resource was not found (eg. group, campaign, otp, shortlink, template, etc.)ApiMethodNotAllowedException - The target resource doesn’t support this HTTP methodAccessDeniedException - You don’t have permission to perform an action (eg. editing a template that was locked, replying to an Whatsapp after more than 24 hours passed from client reply, etc.)ServerErrorException - Something went wrong on SMS Connexion’s side.ApiException - Something went wrong on SMS Connexion’s sideInsufficientBalanceException - Your request incurs charges in excess of your existing balance.InvalidPhoneNumberException - The phone number provided is not validNoCoverageException - There is no coverage for the destination requested (these are rare)InvalidPinException - The PIN provided does not verify with our recordsOtpAlreadyVerifiedException - The OTP was already verifiedOtpCancelledException - You cannot verify an OTP that was cancelledOtpActionNotAllowedException - You cannot cancel an OTP that has non-pending status (eg. was already verified, canceled, or expired)OtpExpiredException - You cannot verify an OTP that was expiredOtpFailedException - The OTP verification has failed because the numbers of max attempts was reachedChannelNotActiveException - Channel is not active. You need to register Viber and Whatsapp by contacting usTemplateNotApprovedException - Template for sending Viber or Whatsapp is not approvedThe error object ( Error ), which is present in all Exceptions, store information about failures.
If you don’t want to rely on our existing Exceptions, you might need to analyze the details of the Error object.
You can retrieve the error object and examine it to learn more about the failure. Choose an appropriate response according on the error type. Check the examples provided to learn how to get the HTTP code and the error object.
A range of different error types are returned by the API, correlated with their HTTP codes:
invalid_param, insufficient_creditinvalid_api_key, invalid_clientnot_foundrate_limitRead the complete list of error types and codes from the API specification.
try:
# Method
except smscx_client.InvalidRequestException as e:
# Code for invalid request
except smscx_client.RateLimitExcedeedException as e:
# Wait some time and retry the request
retry_after = e.headers['X-Rate-Limit-Reset']; # Unix timestamp eg. 1664103086
except smscx_client.ServerErrorException as e:
# Code for this situation
except smscx_client.ApiException as e:
# If you want to analyze the Error object
error_response = json.loads(e.body)
error_type = error_response['error']['type']
error_code = error_response['error']['code']
error_msg = error_response['error']['message']
http_code = e.status
In special cases, when using methods to validate phone numbers in bulk or when adding phone numbers to an existing group, the Error object will contain a list with invalid phone numbers (if the parameter allowInvalid was not set to true or if not a single valid number was detected).
x = json.loads(e.body)
invalid_phone_numbers = x['error']['invalid'];
"""
Returns list of invalid numbers:
[
"+336123",
"+336123",
"+441589945xx",
"+396778143xx",
"+3362599873xx",
]
"""
To detect an API rate limit error, you can catch the Exception RateLimitExcedeedException or check the Error object for error type rate_limit or check if the HTTP code is 429:
try:
# Method
except smscx_client.RateLimitExcedeedException as e:
# Rate limited
retry_after = e.headers['X-Rate-Limit-Reset']; # Unix timestamp eg. 1664103086
The docs folder provides detailed guides for using this library (methods, models, examples).
The examples folder provides an example for each method.
Full documentation of the API is available here.
Read the documentation for each method to get more examples, complete parameter list, expected responses and list of error codes.
| Method | Description |
|---|---|
| get_account_balance() | Get account balance |
| get_channel_pricing() | Get channels pricing |
| get_channel_pricing_by_country_iso() | Get pricing for channel by country iso |
| get_channels_status() | Get status of all channels |
| Method | Description |
|---|---|
| get_application_settings() | Get application settings |
| get_applications_list() | Get applications list |
| get_scopes() | Get scopes |
| Method | Description |
|---|---|
| delete_attachment() | Delete attachment |
| export_attachment_hits_to_csv() | Export attachment hits to CSV |
| export_attachment_hits_to_xlsx() | Export attachment hits to XLSX |
| get_attachment_hits() | Get attachment hits |
| get_attachments_list() | Get attachments list |
| Method | Description |
|---|---|
| get_conversation() | Get conversation |
| get_converstions_list() | Get conversations list |
| mark_conversation_as_read() | Mark conversation as read |
| send_conversation_reply_sms() 💰 | Send conversation reply via SMS |
| send_conversation_reply_viber() 💰 | Send conversation reply via Viber |
| send_conversation_reply_whatsapp() 💰 | Send conversation reply via Whatsapp |
| Method | Description |
|---|---|
| add_contacts_to_group() | Add contacts to group |
| add_contacts_to_group_with_fields() | Add contacts to group with fields (first name, last name, email etc.) |
| create_group() | Create new group |
| delete_contact_from_group() | Delete contact from group |
| delete_group() | Delete group |
| empty_group() | Empty group |
| export_group_to_csv() | Export group to CSV |
| export_group_to_xlsx() | Export group to XLSX |
| get_group_details() | Get group details |
| get_groups_list() | Get list of groups |
| update_contact_from_group() | Update contact from group |
| Method | Description |
|---|---|
| delete_scheduled_multichannel_campaign() | Delete scheduled Multichannel campaign |
| delete_scheduled_multichannel_message() | Delete scheduled Multichannel message |
| estimate_multichannel_campaign() | Estimate Multichannel campaign |
| estimate_multichannel_message() | Estimate Multichannel message |
| send_multichannel_campaign() 💰 | Send Multichannel campaign |
| send_multichannel_message() 💰 | Send Multichannel message |
| Method | Description |
|---|---|
| get_bulk_lookup_status() | Get Bulk Lookup result |
| get_bulk_lookup_campaigns() | Get list of bulk lookup campaigns |
| get_single_lookup_status() | Get Single Lookup result |
| lookup_number() 💰 | Lookup number |
| lookup_numbers() 💰 | Lookup numbers in bulk |
| export_number_lookup_report_to_csv() | Export number lookup campaign to CSV |
| export_number_lookup_report_to_xlsx() | Export number lookup campaign to XLSX |
| validate_number() | Validate number |
| validate_numbers() | Validate numbers in bulk |
| get_available_numbers() | Get available numbers for rent |
| rent_number() 💰 | Rent phone number |
| cancel_rent() | Cancel rent for phone number |
| renew_rent() 💰 | Renew rent for phone number |
| get_rent_status() | Get status of rent |
| get_rented_numbers() | Get list of your rented numbers |
| get_inbound_sms() | Get inbound SMS from rented number |
| edit_rent_settings() | Edit settings for active rent |
| Method | Description |
|---|---|
| get_access_token() | Get access token |
| Method | Description |
|---|---|
| add_contact_to_optouts_list() | Add contact to optouts list |
| delete_contact_from_optouts_list() | Delete contact from optouts list |
| export_optouts_to_csv() | Export optouts to CSV |
| export_optouts_to_xlsx() | Export optouts to XLSX |
| get_optouts_list() | Get optouts list |
| Method | Description |
|---|---|
| create_originator() | Create new originator |
| delete_originator() | Delete originator |
| get_originators_list() | Get originators list |
| Method | Description |
|---|---|
| cancel_otp() | Cancel OTP |
| get_otp_status() | Get OTP status |
| new_otp() 💰 | New OTP |
| verify_otp() | Verify OTP |
| Method | Description |
|---|---|
| export_advanced_report_to_csv() | Export advanced report to CSV |
| export_advanced_report_to_xlsx() | Export advanced report to XLSX |
| export_campaign_report_to_csv() | Export campaign report to CSV |
| export_campaign_report_to_xlsx() | Export campaign report to XLSX |
| get_advanced_report() | Get advanced report |
| get_campaign_report() | Get campaign report |
| get_campaigns_list() | Get list of sent campaigns |
| get_single_report() | Get report for single SMS or Viber or Whatsapp or Multichannel |
| get_summary_reports() | Get summary reports for a dimension |
| Method | Description |
|---|---|
| create_shortlink() | Create shortlink |
| delete_shortlink() | Delete shortlink |
| export_shortlink_hits_to_csv() | Export shortlink hits to CSV |
| export_shortlink_hits_to_xlsx() | Export shortlink hits to XLSX |
| get_shortlink_hits() | Get shortlink hits |
| get_shortlinks_list() | Get shortlinks list |
| update_shortlink() | Update shortlink |
| Method | Description |
|---|---|
| delete_scheduled_sms() | Delete scheduled SMS |
| delete_scheduled_sms_campaign() | Delete scheduled SMS campaign |
| estimate_sms() | Estimate new SMS |
| estimate_sms_campaign() | Estimate SMS campaign |
| send_sms() 💰 | Send SMS |
| send_sms_campaign() 💰 | Send SMS campaign |
| Method | Description |
|---|---|
| create_template() | Create template |
| delete_template() | Delete template |
| get_template() | Get template |
| get_templates_list() | Get templates list |
| update_template() | Update template |
| Method | Description |
|---|---|
| delete_scheduled_viber_campaign() | Delete scheduled Viber campaign |
| delete_scheduled_viber_message() | Delete scheduled Viber message |
| estimate_viber_campaign() | Estimate Viber campaign |
| estimate_viber_message() | Estimate Viber message |
| send_viber_campaign() 💰 | Send Viber campaign |
| send_viber_message() 💰 | Send Viber message |
| Method | Description |
|---|---|
| delete_scheduled_whatsapp_message() | Delete scheduled Whatsapp message |
| estimate_whatsapp_message() | Estimate Whatsapp message |
| send_whatsapp_message() 💰 | Send Whatsapp message |
0.1.131.0.2Apache 2.0 © 2022 SMS Connexion
FAQs
SMS API
We found that smscx-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Popular npm packages like eslint-config-prettier were compromised after a phishing attack stole a maintainer’s token, spreading malicious updates.
Security News
/Research
A phishing attack targeted developers using a typosquatted npm domain (npnjs.com) to steal credentials via fake login pages - watch out for similar scams.
Security News
Knip hits 500 releases with v5.62.0, refining TypeScript config detection and updating plugins as monthly npm downloads approach 12M.