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 and ENCODING_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 given remove 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
tags

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, if RESET 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, if RESET then the value is reset to its XMS default, and if set to a GroupAutoUpdate 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 and MtBatchTextSmsCreate, respectively.

tags

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, if RESET 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, if RESET 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, if RESET 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, if RESET 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, if RESET 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, if RESET 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 or GroupResponse.

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
get(page)[source]

Downloads a specific page.

Parameters:page (int) – number of the page to fetch
Returns:a page
Return type:Page
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
next()[source]
clx.xms.api.RESET = <clx.xms.api.Reset object>

Object used to indicate that a XMS field should be reset to its default value.

class clx.xms.api.ReportType[source]

Bases: object

A collection of known delivery report types.

These values are known to be valid in MtSmsBatch.delivery_report.

FULL = 'full'
NONE = 'none'
PER_RECIPIENT = 'per_recipient'
SUMMARY = 'summary'
class clx.xms.api.Reset[source]

Bases: object

A class whose instances indicate that a value should be reset.

This is used when updating previously created XMS objects. Note, it is typically not necessary to created new objects of this type, instead use the constant RESET.

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:

MtBatchDryRunResult

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:

MtBatchBinarySmsResult

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:

MtBatchTextSmsResult

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
fetch_batch_tags(batch_id)[source]

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:

Pages

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. When None 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:

BatchDeliveryReport

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]
fetch_group_tags(group_id)[source]

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:

Pages

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:

Pages

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:

BatchRecipientDeliveryReport

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:

MtBatchTextSmsResult

replace_batch_tags(batch_id, tags)[source]

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:

GroupResult

replace_group_tags(group_id, tags)[source]

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:

MtBatchTextSmsResult

update_batch_tags(batch_id, tags_to_add, tags_to_remove)[source]

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:

GroupResult

update_group_tags(group_id, tags_to_add, tags_to_remove)[source]

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 value mt_text then an MtBatchSmsTextCreate object is returned, if the value is mt_binary then an MtBatchTextSmsCreate 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
clx.xms.deserialize.tags(response)[source]

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
exception clx.xms.exceptions.UnauthorizedException(service_plan_id, token)[source]

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
service_plan_id

The service plan identifier that did not pass authentication.

Type:str
token

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
clx.xms.serialize.tags(tag_coll)[source]

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
clx.xms.serialize.tags_update(tags_to_add, tags_to_remove)[source]

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.