clx.xms package¶
Submodules¶
clx.xms.api module¶
The classes in this module represent objects sent and received from the XMS REST API.
-
class
clx.xms.api.
BatchDeliveryReport
[source]¶ Bases:
object
Batch delivery report.
A batch delivery report is divided into a number of buckets and each such bucket contain statistics about batch messages having a specific delivery status. The
statuses
property contains the various buckets.-
batch_id
¶ Identifier of the batch that this report covers.
Type: str
-
total_message_count
¶ The total number of messages sent as part of this batch.
Type: int
-
statuses
¶ The batch status buckets. This array describes the aggregated status for the batch where each array element contains information about messages having a certain delivery status and delivery code.
Type: list[BatchDeliveryReportStatus]
-
-
class
clx.xms.api.
BatchDeliveryReportStatus
[source]¶ Bases:
object
Aggregated statistics for a given batch.
This represents the delivery statistics for a given statistics bucket. See
BatchDeliveryReport
.-
code
¶ The delivery status code for this recipient bucket.
Type: int
-
status
¶ The delivery status for this recipient bucket.
Type: str
-
count
¶ The number of recipients belonging to this bucket.
Type: int
-
recipients
¶ The recipients having this status.
Note, this is non-empty only if a full delivery report has been requested.
Type: set[str]
-
-
class
clx.xms.api.
BatchRecipientDeliveryReport
[source]¶ Bases:
object
A delivery report for an individual batch recipient.
-
batch_id
¶ The batch identifier.
Type: string
-
recipient
¶ The recipient address.
Type: string
-
code
¶ The delivery code.
Type: int
-
status
¶ The delivery status.
Type: int
-
status_message
¶ The delivery status message. The status message is not always available and the attribute is set to None in those cases.
Type: string or None
-
operator
¶ The recipient’s mobile operator. If the operator is not known, then this is set to None.
Type: string or None
-
status_at
¶ The time at delivery.
Type: datetime
-
operator_status_at
¶ The time of delivery as reported by operator.
Type: datetime or None
-
-
class
clx.xms.api.
DeliveryReportType
[source]¶ Bases:
object
The types of delivery reports that can be retrieved.
-
FULL
= 'full'¶ Indicates a full batch delivery report.
This includes per-recipient delivery results. For batches with many destinations such reports may be very large.
-
SUMMARY
= 'summary'¶ Indicates a summary batch delivery report.
The summary delivery report does not include the per-recipient result but rather aggregated statistics about the deliveries.
-
-
class
clx.xms.api.
DeliveryStatus
[source]¶ Bases:
object
A collection of known delivery statuses.
Note, new statuses may be introduced to the XMS API.
-
ABORTED
= 'Aborted'¶ Message was aborted before reaching SMSC.
-
DELIVERED
= 'Delivered'¶ Message has been delivered.
-
DISPATCHED
= 'Dispatched'¶ Message has been dispatched and accepted for delivery by the SMSC.
-
EXPIRED
= 'Expired'¶ Message expired before delivery.
-
FAILED
= 'Failed'¶ Message failed to be delivered.
-
QUEUED
= 'Queued'¶ Message is queued within REST API system and will be dispatched according to the rate of the account.
-
REJECTED
= 'Rejected'¶ Message was rejected by SMSC.
-
UNKNOWN
= 'Unknown'¶ It is not known if message was delivered or not.
-
-
class
clx.xms.api.
DryRunPerRecipient
[source]¶ Bases:
object
Per-recipient dry-run result.
Object of this class only occur within dry-run results. See
MtBatchDryRunResult
.-
recipient
¶ The recipient.
Type: str
-
number_of_parts
¶ Number of message parts needed for the recipient.
Type: int
-
body
¶ Message body sent to this recipient.
Type: str
-
encoding
¶ Indicates the text encoding used for this recipient.
This is one of “text” or “unicode”. See
ENCODING_TEXT
andENCODING_UNICODE
.Type: str
-
ENCODING_TEXT
= 'text'¶ Constant indicating non-unicode encoding.
-
ENCODING_UNICODE
= 'unicode'¶ Constant indicating unicode encoding.
-
-
class
clx.xms.api.
Error
(code, text)[source]¶ Bases:
object
Describes error responses given by XMS.
Parameters: - code (str) – the error code
- text (str) – the human readable error text
-
code
¶ A code that can be used to programmatically recognize the error.
Type: str
-
text
¶ Human readable description of the error.
Type: str
-
class
clx.xms.api.
GroupAutoUpdate
(recipient, add_first_word=None, add_second_word=None, remove_first_word=None, remove_second_word=None)[source]¶ Bases:
object
A description of automatic group updates.
An automatic update is triggered by a mobile originated message to a given number containing special keywords.
When the given recipient receives a mobile originated SMS containing keywords (first and/or second) matching the given
add
arguments then the sender MSISDN is added to the group. Similarly, if the MO is matching the givenremove
keyword arguments then the MSISDN is removed from the group.For example:
GroupAutoUpdate( recipient='12345', add_first_word='add', remove_first_word='remove')
would trigger based solely on the first keyword of the MO message. On the other hand:
GroupAutoUpdate( recipient='12345', add_first_word='alert', add_second_word='add', remove_first_word='alert', remove_second_word='remove')
would trigger only when both the first and second keyword are given in the MO message.
Parameters: - recipient (str) – recipient that triggers this rule
- add_first_word (str or None) – first
add
keyword, default is None. - add_second_word (str or None) – second
add
keyword, default is None. - remove_first_word (str or None) – first
remove
keyword, default is None. - remove_second_word (str or None) – second
remove
keywords, default is None.
-
recipient
¶ The recipient of the mobile originated message. A short code or long number.
Type: str
-
add_word_pair
¶ A two-element tuple holding the first and second keyword that causes the MO sender to be added to the group.
Type: tuple[str or None, str or None]
-
remove_word_pair
¶ A two-element tuple holding the first and second keyword that causes the MO sender to be removed from the group.
Type: tuple[str or None, str or None]
-
class
clx.xms.api.
GroupCreate
[source]¶ Bases:
object
A description of the fields necessary to create a group.
-
name
¶ The group name.
Type: str
-
members
¶ A set of MSISDNs that belong to this group.
Type: set[str]
-
child_groups
¶ A set of groups that in turn belong to this group.
Type: set[str]
-
auto_update
¶ Describes how this group should be auto updated.
If no auto updating should be performed for the group then this value is
None
.Type: GroupAutoUpdate or None
The tags associated to this group.
Type: set[str]
-
-
class
clx.xms.api.
GroupResult
[source]¶ Bases:
object
This class holds the result of a group fetch operation.
This may be used either standalone or as an element of a paged result.
-
group_id
¶ The unique group identifier.
Type: str
-
name
¶ The group name.
Type: str
-
size
¶ The number of members of this group.
Type: int
-
child_groups
¶ A set of groups that in turn belong to this group.
Type: set[str]
-
auto_update
¶ Describes how this group should be auto updated.
If no auto updating should be performed for the group then this value is
None
.Type: GroupAutoUpdate or None
-
created_at
¶ The time at which this group was created.
Type: datetime
-
modified_at
¶ The time when this group was last modified.
Type: datetime
-
-
class
clx.xms.api.
GroupUpdate
[source]¶ Bases:
object
Describes updates that can be performed on a group.
-
name
¶ Updates the group name.
If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a string the name is updated.Type: None or str or Reset
-
member_insertions
¶ The MSISDNs that should be added to this group.
Type: set[str]
-
member_removals
¶ The MSISDNs that should be removed from this group.
Type: set[str]
-
child_group_insertions
¶ The child groups that should be added to this group.
Type: set[str]
-
child_group_removals
¶ The child groups that should be removed from this group.
Type: set[str]
-
add_from_group
¶ Identifier of a group whose members should be added to this group.
Type: str
-
remove_from_group
¶ Identifier of a group whose members should be removed from this group.
Type: str
-
auto_update
¶ Describes how this group should be auto updated.
If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to aGroupAutoUpdate
object the value is updated.Type: None or GroupAutoUpdate or Reset
-
-
class
clx.xms.api.
MoBinarySms
[source]¶ Bases:
clx.xms.api.MoSms
An SMS mobile originated message with binary content.
-
body
¶ The binary message body.
Type: bytes
-
udh
¶ The user data header.
Type: bytes
-
-
class
clx.xms.api.
MoSms
[source]¶ Bases:
object
Base class for SMS mobile originated messages.
Holds fields that are common to both the textual and binary MO classes.
-
message_id
¶ The message identifier.
Type: str
-
recipient
¶ The message recipient. This is a short code or long number.
Type: str
-
sender
¶ The message sender. This is an MSISDN.
Type: str
-
operator
¶ The MCCMNC of the originating operator, if available.
Type: str or None
-
sent_at
¶ The time when this message was sent, if available.
Type: datetime or None
-
received_at
¶ The time when the messaging system received this message.
Type: datetime
-
-
class
clx.xms.api.
MoTextSms
[source]¶ Bases:
clx.xms.api.MoSms
An SMS mobile originated message with textual content.
-
body
¶ The message body.
Type: str
-
keyword
¶ The message keyword, if available.
Type: str or None
-
-
class
clx.xms.api.
MtBatchBinarySmsCreate
[source]¶ Bases:
clx.xms.api.MtBatchSmsCreate
Describes a binary batch.
This class holds all parameters that can be used when creating a binary SMS batch.
-
body
¶ The body of this binary message.
Type: bytes
-
udh
¶ The User Data Header of this binary message.
Type: bytes
-
-
class
clx.xms.api.
MtBatchBinarySmsResult
[source]¶ Bases:
clx.xms.api.MtBatchSmsResult
A binary SMS batch as returned by XMS.
-
body
¶ The body of this binary message.
Type: bytes
-
udh
¶ The User Data Header of this binary message.
Type: bytes
-
-
class
clx.xms.api.
MtBatchBinarySmsUpdate
[source]¶ Bases:
clx.xms.api.MtBatchSmsUpdate
Describes updates to a binary SMS batch.
-
body
¶ The updated binary batch body. If
None
then the existing body is left as-is.Type: bytes or None
-
udh
¶ The updated binary User Data Header. If
None
then the existing UDH is left as-is.Type: bytes or None
-
-
class
clx.xms.api.
MtBatchDryRunResult
[source]¶ Bases:
object
A batch dry run report.
-
number_of_recipients
¶ The number of recipients that would receive the batch message.
Type: int
-
number_of_message
¶ The number of messages that will be sent.
Type: int
-
per_recipient
¶ The per-recipient dry-run result.
Type: list[DryRunPerRecipient]
-
-
class
clx.xms.api.
MtBatchSms
[source]¶ Bases:
object
Base class for all SMS batch classes.
Holds fields that are common to both the create and response classes.
-
recipients
¶ One or more MSISDNs indicating the batch recipients.
Type: set[str]
-
sender
¶ The batch sender, typically a short code or long number.
Type: str
-
delivery_report
¶ The type of delivery report to use for this batch.
Type: str
-
send_at
¶ The time at which this batch should be sent.
Type: datetime
-
expire_at
¶ The time at which this batch should expire.
Type: datetime
-
callback_url
¶ The URL to which callbacks should be sent.
Type: str
-
-
class
clx.xms.api.
MtBatchSmsCreate
[source]¶ Bases:
clx.xms.api.MtBatchSms
Describes parameters available during batch creation.
We can create two kinds of batches, textual and binary, described in the child classes
MtBatchTextSmsCreate
andMtBatchTextSmsCreate
, respectively.The initial set of tags to give the batch.
Type: set[str]
-
class
clx.xms.api.
MtBatchSmsResult
[source]¶ Bases:
clx.xms.api.MtBatchSms
Contains the common fields of text and binary batches.
-
batch_id
¶ The unique batch identifier.
Type: str
-
created_at
¶ Time when this batch was created.
Type: datetime
-
modified_at
¶ Time when this batch was last modified.
Type: datetime
-
canceled
¶ Whether this batch has been canceled.
Type: bool
-
-
class
clx.xms.api.
MtBatchSmsUpdate
[source]¶ Bases:
object
Describes updates that can be performed on text and binary SMS batches.
-
recipient_insertions
¶ The message destinations to add to the batch. This should have zero or more MSISDNs.
Type: set[str]
-
recipient_removals
¶ The message destinations to remove from the batch. This should have zero or more MSISDNs.
Type: set[str]
-
sender
¶ The message originator as a long number or short code. If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a string the sender is updated.Type: str or None or Reset
-
delivery_report
¶ Description of how to update the batch delivery report value. If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a string the delivery report value is updated.See
ReportType
for valid report types.Type: str or None or Reset
-
send_at
¶ Description of how to update the batch send at value. If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a date time the send at value is updated.Type: datetime or None or Reset
-
expire_at
¶ Description of how to update the batch expire at value. If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a date time the expire at value is updated.Type: datetime or None or Reset
-
callback_url
¶ Description of how to update the batch callback URL. If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a string the callback URL value is updated.Type: str or None or Reset
-
-
class
clx.xms.api.
MtBatchTextSmsCreate
[source]¶ Bases:
clx.xms.api.MtBatchSmsCreate
Class whose fields describe a text batch.
-
body
¶ The message body or template.
Type: str
-
parameters
¶ The template parameters.
This property is only relevant is the
body
property is a template. This is expected to be an associative array mapping parameter keys to associative arrays themselves mapping recipient numbers to substitution strings.More concretely we may have for the parameterized message “Hello, ${name}!” have:
batch.parameters = { 'name': { '123456789': 'Mary', '987654321': 'Joe', 'default': 'valued customer' } }
And the recipient with MSISDN “123456789” would then receive the message “Hello, Mary!”.
Note the use of “default” to indicate the substitution for recipients not explicitly given. For example, the recipient “555555555” would receive the message “Hello, valued customer!”.
Type: dict[str, dict[str, str]]
-
-
class
clx.xms.api.
MtBatchTextSmsResult
[source]¶ Bases:
clx.xms.api.MtBatchSmsResult
A textual batch as returned by the XMS endpoint.
This differs from the batch creation definition by the addition of, for example, the batch identifier and the creation time.
-
body
¶ The message body or template. See
MtBatchTextSmsCreate.parameters
.Type: str
-
parameters
¶ The template parameters.
type dict[str, dict[str, str]]
-
-
class
clx.xms.api.
MtBatchTextSmsUpdate
[source]¶ Bases:
clx.xms.api.MtBatchSmsUpdate
Class that the update operations that can be performed on a text batch.
-
body
¶ The updated batch message body. If
None
then the current batch message is kept.Type: str or None
-
parameters
¶ Description of how to update the batch parameters. If
None
then the current value is kept, ifRESET
then the value is reset to its XMS default, and if set to a dictionary the parameters value is updated.Type: dict or None or Reset
-
-
class
clx.xms.api.
Page
[source]¶ Bases:
object
A page of elements.
The element type depends on the type of page that has been retrieved. Typically it is one of
MtSmsBatchResponse
orGroupResponse
.-
page
¶ The page number, starting from zero.
Type: int
-
page
The number of elements on this page.
Type: int
-
total_size
¶ The total number of elements across all fetched pages.
Type: int
-
content
¶ The page elements.
Type: list[obj]
-
-
class
clx.xms.api.
Pages
(worker)[source]¶ Bases:
object
A paged result.
It is possible to, for example, fetch individual pages or iterate over all pages.
Parameters: worker – worker function that fetches pages
-
class
clx.xms.api.
PagesIterator
(pages)[source]¶ Bases:
object
An iterator over a paged result.
The key is the page number and the value corresponds to the content of the pages.
Parameters: pages (Pages) – the pages that we are iterating over
-
clx.xms.api.
RESET
= <clx.xms.api.Reset object>¶ Object used to indicate that a XMS field should be reset to its default value.
clx.xms.client module¶
XMS Client module
-
class
clx.xms.client.
Client
(service_plan_id, token, endpoint='https://api.clxcommunications.com/xms', timeout=30.0)[source]¶ Bases:
object
Client used to communicate with the XMS server.
Parameters: - service_plan_id (str) – service plan identifier
- token (str) – authentication token
- endpoint (str) – URL to XMS endpoint
- timeout (float) – Connection and read timeout, in seconds
This class will use the Requests library to communicate with XMS. It is intended as a long lived object and can handle multiple requests.
For example, to send a simple parameterized text batch to three recipients we may use code such as:
client = clx.xms.Client('{my-service-plan-id}', '{my-token}') try: batch_params = clx.xms.api.MtBatchTextSmsCreate() batch_params.sender = '12345' batch_params.recipients = ['987654321', '123456789', '567894321'] batch_params.body = 'Hello, ${name}!' batch_params.parameters = { 'name': { '987654321': 'Mary', '123456789': 'Joe', 'default': 'valued customer' } } batch = client.create_text_batch(batch_params) print('The batch was given ID %s' % batch.batch_id) except Exception as ex: print('Error creating batch: %s' % str(ex))
and to fetch a batch we may use the code (with
client
being the same variable as above):try: batch = client.fetch_batch('{a batch identifier}') print('The batch was sent from %s' % batch.sender()) except Exception as ex: print('Error fetching batch: %s' % str(ex))
-
DEFAULT_ENDPOINT
= 'https://api.clxcommunications.com/xms'¶ The default XMS endpoint URL. This is the endpoint that will be used unless a custom one is specified in the
Client
constructor.
-
DEFAULT_TIMEOUT
= 30.0¶ The default timeout value in seconds. This is used unless a custom timeout value is specified in
timeout
.
-
cancel_batch
(batch_id)[source]¶ Cancels the batch with the given batch identifier.
Parameters: batch_id (str) – the batch identifier Returns: nothing
-
create_batch
(batch)[source]¶ Creates the given batch.
Parameters: batch (MtBatchTextSmsCreate or MtBatchBinarySmsCreate) – the text or binary batch to create Returns: the batch result Return type: MtBatchTextSmsResult or MtBatchBinarySmsResult
-
create_batch_dry_run
(batch, num_recipients=None)[source]¶ Simulates sending the given batch.
The method takes an optional argument for instructing XMS to respond with per-recipient statistics, if non-null then this number of recipients will be returned in the result.
Parameters: - batch (MtBatchSmsCreate) – the batch to simulate
- num_recipients (int or None) – number of recipients to show in per-recipient result
Returns: result of dry-run
Return type:
-
create_binary_message
(sender, recipient, udh, body)[source]¶ Creates a text message to a single recipient.
This is a convenience method that creates a text batch having a single recipient.
Parameters: - sender (str) – the message sender
- recipient (str) – the message recipient
- udh (binary) – the message User Data Header
- body (binary) – the message binary body
Returns: the created batch
Return type:
-
create_group
(group)[source]¶ Creates the given group.
Parameters: group (GroupCreate) – group description Returns: the created group Return type: GroupResult
-
create_text_message
(sender, recipient, body)[source]¶ Creates a text message to a single recipient.
This is a convenience method that creates a text batch having a single recipient.
Parameters: - sender (str) – the message sender
- recipient (str) – the message recipient
- body (str) – the message body
Returns: the created batch
Return type:
-
delete_group
(group_id)[source]¶ Deletes the group with the given group identifier.
Parameters: group_id (str) – the group identifier Returns: Nothing
-
endpoint
¶ The XMS endpoint used by this client.
Type: str
-
fetch_batch
(batch_id)[source]¶ Fetches the batch with the given batch identifier.
Parameters: batch_id (str) – batch identifier Returns: the corresponding batch Return type: MtBatchSmsResult
Fetches the tags associated with the given batch.
Parameters: batch_id (str) – the batch identifier Returns: a set of tags Return type: set[str]
-
fetch_batches
(page_size=None, senders=None, tags=None, start_date=None, end_date=None)[source]¶ Fetch the batches matching the given filter.
Note, calling this method does not actually cause any network traffic. Listing batches in XMS may return the result over multiple pages and this call therefore returns an object of the type
Pages
, which will fetch result pages as needed.Parameters: - page_size (int) – Maximum number of batches to retrieve per page.
- senders (set[str] or None) – Fetch only batches having one of these senders.
- tags (set[str] or None) – Fetch only batches having one or more of these tags.
- start_date (date or None) – Fetch only batches sent at or after this date.
- end_date (date or None) – Fetch only batches sent before this date.
Returns: the result pages
Return type:
-
fetch_delivery_report
(batch_id, kind=None, status=None, code=None)[source]¶ Fetches a delivery report for a batch.
The report type can be one of
None
, “full”, or “summary”. When “full” the report includes the individual recipients. WhenNone
then the XMS default value is used.The report can be further limited by status and code. For example, to retrieve a summary report limited to messages having delivery status “Delivered” or “Failed” and codes “0”, “11”, or “400”, one could call:
client.fetch_delivery_report( 'MyBatchId', 'summary', {'Delivered', 'Failed'}, {0, 11, 400});
If the non-identifier parameters are left unspecified then the XMS defaults are used. In particular, all statuses and codes are included in the report.
Parameters: - batch_id (str) – identifier of the batch
- kind (str or None) – delivery report type
- status (set[str]) – statuses to fetch
- code (set[int]) – codes to fetch
Returns: the batch delivery report
Return type:
-
fetch_group
(group_id)[source]¶ Fetches the group with the given group identifier.
Parameters: group_id (str) – group identifier Returns: the corresponding group
-
fetch_group_members
(group_id)[source]¶ Fetches the that belong to the given group.
Parameters: group_id (str) – the group identifier Returns: a set of MSISDNs Return type: set[str]
Fetches the tags associated with the given group.
Parameters: group_id (str) – the group identifier Returns: a set of tags Return type: set[str]
-
fetch_groups
(page_size=None, tags=None)[source]¶ Fetch the groups matching the given filter.
Note, calling this method does not actually cause any network traffic. Listing groups in XMS may return the result over multiple pages and this call therefore returns an object of the type
Pages
, which will fetch result pages as needed.Parameters: - page_size (int or None) – Maximum number of groups to retrieve per page.
- tags (set[str] or None) – Fetch only groups having or or more of these tags.
Returns: the result pages
Return type:
-
fetch_inbound
(inbound_id)[source]¶ Fetches the inbound message with the given identifier.
The returned message is either textual or binary.
Parameters: inbound_id (str) – message identifier Returns: the fetched message Return type: MoTextSms or MoBinarySms
-
fetch_inbounds
(page_size=None, recipients=None, start_date=None, end_date=None)[source]¶ Fetch inbound messages matching the given filter.
Note, calling this method does not actually cause any network traffic. Listing inbound messages in XMS may return the result over multiple pages and this call therefore returns an object of the type
Pages
, which will fetch result pages as needed.Parameters: - page_size (int or None) – The maximum number of messages to retrieve per page.
- recipients (set[str] or None) – Fetch only messages having one of these recipients.
- start_date (date or None) – Fetch only messages received at or after this date.
- end_date (date or None) – Fetch only messages received before this date.
Returns: the result pages
Return type:
-
fetch_recipient_delivery_report
(batch_id, recipient)[source]¶ Fetches a delivery report for a specific batch recipient.
Parameters: - batch_id (str) – the batch identifier
- recipient (str) – the batch recipient
Returns: the delivery report
Return type:
-
replace_batch
(batch_id, batch)[source]¶ Replaces the batch with the given ID with the given batch.
Parameters: - batch_id (str) – identifier of the batch
- batch (MtBatchTextSmsCreate or MtBatchBinarySmsCreate) – the replacement batch
Returns: the resulting batch
Return type:
Replaces the tags of the given batch.
Parameters: - batch_id (str) – identifier of the batch
- tags (set[str]) – the new set of batch tags
Returns: the new batch tags
Return type: set[str]
-
replace_group
(group_id, group)[source]¶ Replaces the group with the given group identifier.
Parameters: - group_id (str) – identifier of the group
- group (GroupCreate) – new group description
Returns: the group after replacement
Return type:
Replaces the tags of the given group.
Parameters: - group_id (str) – identifier of the group
- tags (set[str]) – the new set of group tags
Returns: the new group tags
Return type: set[str]
-
service_plan_id
¶ The service plan identifier used for this client.
Type: str
-
timeout
¶ The timeout value used for this client. In seconds. The connection and read timeout, in seconds, used in communication with XMS. The default is specified by the constant
DEFAULT_TIMEOUT
.type: float
-
token
¶ The authentication token used for this client.
Type: str
-
update_batch
(batch_id, batch)[source]¶ Updates the text batch with the given identifier.
Parameters: - batch_id (str) – identifier of the batch
- batch (MtBatchTextSmsUpdate or MtBatchBinarySmsUpdate) – the update description
Returns: the updated batch
Return type:
Updates the tags of the given batch.
Parameters: - batch_id (str) – batch identifier
- tags_to_add (set[str]) – tags to add to batch
- tags_to_remove (set[str]) – tags to remove from batch
Returns: the updated batch tags
Return type: set[str]
-
update_group
(group_id, group)[source]¶ Updates the group with the given identifier.
Parameters: - group_id (str) – identifier of the group
- group (GroupUpdate) – the update description
Returns: the updated batch
Return type:
Updates the tags of the given group.
Parameters: - group_id (str) – group identifier
- tags_to_add (set[str]) – tags to add to group
- tags_to_remove (set[str]) – tags to remove from group
Returns: the updated group tags
Return type: set[str]
clx.xms.deserialize module¶
JSON deserializer for API classes.
Note, this module is mainly intended for internal use and the API may change in the future
-
clx.xms.deserialize.
batch_delivery_report
(response)[source]¶ Reads a JSON blob describing a batch delivery report.
Parameters: response (Response) – An XMS response carrying a JSON body Returns: the parsed batch delivery report Return type: BatchDeliveryReport Raises: UnexpectedResponseException – if the JSON contained an unexpected message type
-
clx.xms.deserialize.
batch_dry_run_result
(response)[source]¶ Reads a JSON formatted string describing a dry-run result.
Parameters: response (Response) – the response object to interpret Returns: the parsed result Return type: MtBatchDryRunResult
-
clx.xms.deserialize.
batch_recipient_delivery_report
(response)[source]¶ Reads a batch recipient delivery report from the given JSON text.
Parameters: response (Response) – an XMS response Returns: a delivery report Return type: BatchRecipientDeliveryReport Raises: UnexpectedResponseException – if the JSON contained an unexpected message type
-
clx.xms.deserialize.
batch_result
(response)[source]¶ Reads a request response containing a batch result.
If the
type
field has the valuemt_text
then anMtBatchSmsTextCreate
object is returned, if the value ismt_binary
then anMtBatchTextSmsCreate
object is returned, otherwise an exception is thrown.Parameters: response (Response) – the response object to interpret Returns: the parsed result Return type: MtBatchTextSmsResult or MtBatchBinarySmsResult Raises: UnexpectedResponseException – if the JSON contained an unexpected message type
-
clx.xms.deserialize.
batches_page
(response)[source]¶ Reads a JSON blob describing a page of batches.
Parameters: response (Response) – the response object to interpret Returns: the parsed page Return type: Page Raises: UnexpectedResponseException – if the JSON contained an unexpected message type
-
clx.xms.deserialize.
error
(response)[source]¶ Reads a JSON blob containing an error response.
Parameters: response (Response) – an XMS response Returns: the decoded error Return type: Error
-
clx.xms.deserialize.
group_members
(response)[source]¶ Reads a JSON blob containing a set of group members.
Parameters: response (Response) – an XMS response Returns: a set of MSISDNs Return type: set[str]
-
clx.xms.deserialize.
group_result
(response)[source]¶ Parses a group response from the given JSON text.
Parameters: response (Response) – an XMS response Returns: the deserialized group response Return type: GroupResult
-
clx.xms.deserialize.
groups_page
(response)[source]¶ Parses a page of groups from the given JSON text.
Parameters: response (Response) – an XMS response Returns: the created page of groups Return type: Page
-
clx.xms.deserialize.
inbounds_page
(response)[source]¶ Reads a JSON blob describing a page of MO messages.
Parameters: response (Response) – an XMS response Returns: the parsed page Return type: Page Raises: UnexpectedResponseException – if the JSON contained an unexpected message type
-
clx.xms.deserialize.
mo_sms
(response)[source]¶ Reads an XMS response containing an MO message.
Parameters: response (Response) – an XMS response Returns: the MO message found in the response Return type: MoSms Raises: UnexpectedResponseException – if the JSON contained an unexpected message type
Reads a JSON blob containing a list of tags.
Parameters: response (Response) – an XMS response Returns: a set of tags Return type: set[str]
clx.xms.exceptions module¶
Collection of exceptions raised by the XMS SDK.
The exceptions raised by the API all inherit from the base class
ApiException
.
-
exception
clx.xms.exceptions.
ApiException
[source]¶ Bases:
exceptions.Exception
Base class for exceptions thrown within the XMS SDK
-
exception
clx.xms.exceptions.
ErrorResponseException
(message, code)[source]¶ Bases:
clx.xms.exceptions.ApiException
Exception used when XMS responded with an error message.
Parameters: - message (str) – the human readable error message
- code (str) – the machine readable error code
-
error_code
¶ The machine readable error code.
Type: str
-
exception
clx.xms.exceptions.
NotFoundException
(url)[source]¶ Bases:
clx.xms.exceptions.ApiException
Exception indicating that a requested resources did not exist in XMS.
This exception is thrown, for example, when attempting to retrieve a batch with an invalid batch identifier.
Parameters: url (str) – URL to the missing resource. -
url
¶ The failing URL.
Type: str
-
Bases:
clx.xms.exceptions.ApiException
Exception indicating that XMS did not accept the service plan ID and authentication token.
Parameters: - service_plan_id (str) – the service plan identifier
- token (str) – the authentication token
The service plan identifier that did not pass authentication.
Type: str
The authentication token that was not accepted.
Type: str
-
exception
clx.xms.exceptions.
UnexpectedResponseException
(message, http_body)[source]¶ Bases:
clx.xms.exceptions.ApiException
Raised when XMS gave an unexpected response
Parameters: - message (str) – useful message explaining the problem
- http_body (str) – the unexpected HTTP body
-
http_body
¶ The unexpected HTTP body.
Type: str
clx.xms.serialize module¶
JSON serializes for XMS API object classes.
Note, this module is mainly intended for internal use and the API may change in the future
-
clx.xms.serialize.
binary_batch
(batch)[source]¶ Serializes the given binary batch into JSON.
Parameters: batch (MtBatchBinarySmsCreate) – the batch to serialize Returns: dictionary suitable for JSON serialization
-
clx.xms.serialize.
binary_batch_update
(batch)[source]¶ Serializes the given binary batch update into JSON.
Parameters: batch (MtBatchBinarySmsUpdate) – the batch update to serialize Returns: dictionary suitable for JSON serialization Return type: dict
-
clx.xms.serialize.
group_create
(group)[source]¶ Serializes the given group create object to JSON.
Parameters: group (GroupCreate) – the group to serialize Returns: dictionary suitable for JSON serialization
-
clx.xms.serialize.
group_update
(obj)[source]¶ Serializes the given group update object to JSON.
Parameters: obj (GroupUpdate) – the group update to serialize Returns: a dictionary suitable for JSON serialization Return type: dict
Serializes the given tags to a JSON string.
Parameters: tag_coll (set[str]) – a set of tags Returns: a dictionary suitable for JSON serialization Return type: dict
Serializes the given tag updates to a JSON string.
Parameters: - tags_to_add (set[str]) – list of tags
- tags_to_remove (str[str]) – list of tags
Returns: a dictionary suitable for JSON serialization
Return type: dict
-
clx.xms.serialize.
text_batch
(batch)[source]¶ Serializes the given text batch into JSON.
Parameters: batch (MtBatchTextSmsCreate) – the batch to serialize Returns: dictionary suitable for JSON serialization
-
clx.xms.serialize.
text_batch_update
(batch)[source]¶ Serializes the given text batch update into JSON.
Parameters: batch (MtBatchTextSmsUpdate) – the batch update to serialize Returns: dictionary suitable for JSON serialization Return type: dict
Module contents¶
The clx.xms
package.