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.

clx.xms package¶

Submodules¶

clx.xms.api module¶

clx.xms.client module¶

clx.xms.deserialize module¶

clx.xms.exceptions module¶

clx.xms.serialize module¶

Module contents¶

Table Of Contents

Related Topics

This Page