Devices

Create, look up, and list several supported device types. Note that some device types must be registered from the mobile or web SDKs.

Channels

class urbanairship.devices.devicelist.ChannelInfo(airship)

Information object for iOS, Android, Amazon, web, and open channels.

Parameters:

address – Replaces push_address for open channels.
alias – Alias associated with this device, if any.
background – Bool; whether the device is opted in to background push.
channel_id – Channel ID for the device.
created – UTC datetime when the system initially saw the device.
device_type – Type of the device, e.g. ios.
installed – Bool; whether the app is installed on the device.
last_registration – UTC datetime when the system last received a registration call for the device.
named_user_id – Named user associated with this device, if any.
opt_in – Bool; whether the device is opted in to push or other visible notifications.
push_address – Address we use to push to the device (device token, GCM registration ID, etc,). Not present for open channels (see address above).
tag_groups – Tags associated with non-“device” tag groups, if any.
tags – List of tags associated with this device, if any.
ios – iOS specific information, e.g. badge and quiet_time.
open – Open channel specific information, e.g. identifiers and open_platform_name.
web – Web notify specific information, e.g. subscription.
named_user_id – A customer-chosen ID that represents the device user.
device_attributes – Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type.
attributes – A dictionary of attributes that you’ve associated with the channel.
commercial_opted_in – The date-time when a user gave explicit permission to receive commercial emails.
commcercial_opted_out – The date-time when a user explicitly denied permission to receive commercial emails.
transactional_opted_in – The date-time when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
transactional_opted_out – The date-time when a user explicitly denied permission to receive transactional emails.

lookup(channel_id: str): Fetch metadata from a channel ID

class urbanairship.devices.devicelist.DeviceInfo(airship: BaseClient)

Information object for a single device.

Parameters:

active – bool; Whether the device is opted in to push or other visible notifications.
alias – Alias associated with this device, if any.
created – UTC datetime when the system initially saw the device.
device_type – Type of the device, e.g. device_token, apid.
id – Device identifier. Also available at the attribute named by the device_type.
tags – List of tags associated with this device, if any.
apid – Same as device identifier if apid device type.
device_token – Same as device identifier if device_token device type.

class urbanairship.devices.devicelist.DeviceTokenList(airship, limit=None)

Iterator for listing all device tokens for this application.

Parameters:: limit – Number of entries to fetch in each page request.
Returns:: Each next returns a DeviceInfo object.

class urbanairship.devices.devicelist.ChannelList(airship, limit=None, start_channel=None)

Iterator for listing all channels for this application.

Parameters:

limit – Number of entries to fetch in each page request.
start_channel – uuid representing the channel_id to start with.

Returns:

Each next returns a ChannelInfo object.

class urbanairship.devices.devicelist.APIDList(airship, limit=None)

Iterator for listing all APIDs for this application.

Parameters:: limit – Number of entries to fetch in each page request.
Returns:: Each next returns a DeviceInfo object.

Channel Uninstall

class urbanairship.devices.channel_uninstall.ChannelUninstall(airship: BaseClient)

Uninstalls a channel id.

Parameters:: airship – Required. An urbanairship.Airship instance

uninstall(channels: List[str]) → Response

Perform the channel uninstall on a list of channel UUIDs.

Parameters:: channels – Required. A list of channel_id UUIDs.

Open Channels

class urbanairship.devices.open_channel.OpenChannel(airship: BaseClient)

Represents an open channel.

Parameters:

channel_id – The Airship generated channel_id value for the open channel
address – The open channel’s address
open_platform – The open platform associated with the channel

create() → Response: Create this OpenChannel object with the API.

update() → Response: Update this OpenChannel object.

classmethod from_payload(payload: Dict, airship: BaseClient): Instantiate an OpenChannel from a payload.

lookup(channel_id: str): Retrieves an open channel from the provided channel ID.

uninstall() → Response: Mark this OpenChannel object uninstalled

SMS

Create, register, opt-out and uninstall an Sms object.

Parameters:

airship – Required. An urbanairship.Airship object instantiated with master authentication.
sender – Required. The a number that recipients will receive SMS notifications from. This must match your Urban Airship configuration.
msisdn – Required. The mobile phone number you want to register as an SMS channel (or send a request to opt-in).
opted_in – A datetime.datetime object that represents the date and time when explicit permission was received from the user to receive messages. This is required for use with CreateAndSend.
opted_out – Optional. A datetime.datetime object that represents the date and time when a user opted out of SMS messages.
opt_in_mode – Optional. The opt-in mode for registering the channel. classic is the default when unspecified, double creates a double_opt_in event.
properties – Optional. An object containing event properties. You can use these properties to filter the double opt-in event and reference them in your message content by using handlebars. Items in the properties object are limited to a 255-character maximum string length.
template_fields – For use with CreateAndSend with inline templates. A dict of template field names and their substitution values.
locale_country – The ISO 3166 two-character country code. The value for this field becomes a tag in the ua_locale_country tag group.
locale_language – The ISO 639-1 two-character language code. The value for this field becomes a tag in the ua_locale_language tag group.
timezone – The IANA identifier for a timezone, e.g. “America/Los_Angeles”. The value in this field becomes a tag in the timezone tag group.

register(opted_in: datetime | None = None) → Response

Register an Sms channel with the sender ID and MSISDN

Parameters:: opted_in – Optional UTC ISO 8601 datetime string that represents the date and time when explicit permission was received from the user to receive messages.
Returns:: The response object from the api.

update(channel_id: str | None = None) → Response

Updates properties of an existing SMS channel.

Parameters:: Optional (channel_id) – An existing airship-provided channel_id UUID for an SMS channel. If this object was created with this class, the channel_id value should be assigned. Otherwise, pass it here. Other values are set as properties on an instance of this class before the update call.
Returns:: The response object from the API

opt_out() → Response

Mark an sms channel at opted-out by sender ID and MSISDN

Returns:: the response object from the api

uninstall() → Response

Uninstall and remove all associated data from Airship systems. Channel cannot be opted-in again. Use with caution.

Returns:: the response object from the api

lookup() → Response

Look up Sms channel information

Returns:: the response object from the api

class urbanairship.devices.sms.KeywordInteraction(airship: BaseClient, keyword: str, msisdn: str, sender_ids: List[str], timestamp: datetime | None = None)

Trigger Mobile Originated (MO) keyword interactions on behalf of an MSISDN.

Parameters:

airship – Required. An urbanairship.Airship instance.
keyword – Required. The keyword to use for the interaction.
msisdn – Required. The MSISDN to use for the interacton.
sender_ids – Required. A list of sender id values to use for the interaction.
timestamp – Optional. A datetime.datetime representing the time of the interaction.

post() → Response: Send the interaction

class urbanairship.devices.sms.SmsCustomResponse(airship: BaseClient, mobile_originated_id: str, sms: Dict | None = None, mms: Dict | None = None)

Respond to a mobile originated message based on a keyword consumed by your custom response webhook, using a mobile-originated ID. Please see the documentation at https://docs.airship.com/api/ua/?http#operation-api-sms-custom-response-post for details on use of this feature.

One of mms or sms is required.

Parameters:

airship – [required] An urbanairship.Airship instance, created with bearer token authentication.
mobile_originated_id – [required] The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you’re issuing a custom response to.
sms – [optional] An SMS platform override object, created using ua.sms(). This defines the message sent in response.
mms – [optional] An MMS platform override object, created using us.mms(). The defines the message sent in response.

send() → Dict

Sends the response using the mobile_originated_id value

Returns:: An API response dictionary

Email

Register and uninstall an Email object.

Please see the email documentation for important information about opt-in times and email types. https://docs.airship.com/api/ua/#tag-email

Parameters:

address – Required. The email address the object represents.
commercial_opted_in – Optional. A string in ISO 8601 format that represents the time explicit permission was received from the user to accept commercial emails.
commercial_opted_out – Optional. A string in ISO 8601 format that represents the time a user opted out of commercial emails.
transactional_opted_in – Optional. A string in ISO 8601 format that represents the time a user explicitly opted in to transactional emails.
transactional_opted_out – Optional. A string in ISO 8601 formation that represents the time a user explicitly opted out of transactional emails.
locale_country – Optional. The device property tag related to locale country setting.
locale_language – Optional. The device property tag related to locale language setting.
opt_in_mode – Optional. The opt-in mode for registering the channel. classic is the default when unspecified, double creates a double_opt_in event.
properties – Optional. An object containing event properties. You can use these properties to filter the double opt-in event and reference them in your message content by using handlebars. Items in the properties object are limited to a 255-character maximum string length.
timezone – Optional. The deice property tag related to timezone setting.
template_fields – For use with CreateAndSend with inline templates. A dict of template field names and their substitution values.

register() → Response

Create a new email channel or unsubscribe an existing email channel from receiving commercial emails. To unsubscribe an existing channel, set email_opt_in_level to none.

Returns:: The response object from the API.

update(channel_id: str | None = None) → Response

Updates an existing email channel.

Parameters:: Optional (channel_id) – An existing airship-provided channel_id UUID for an email channel. If this object was created with this class, the channel_id value should be assigned. Otherwise, pass it here. Other values are set as properties on an instance of this class before the update call.

uninstall() → Response

Removes an email address from Urban Airship. Use with caution. If the uninstalled email address opts-in again, it will generate a new channel_id. The new channel_id cannot be reassociated with any opt-in information, tags, named users, insight reports, or other information from the uninstalled email channel.

Returns:: The response object from the API

class urbanairship.devices.email.EmailTags(airship: BaseClient, address: str)

Add, remove or set tags for a list of email addresses

Parameters:: address – an email address to mutate tags for

add(group: str, tags: List[str]) → None: add tags to a given tag group :param group: the tag group to add to :param tags: a list of tags to add

remove(group: str, tags: List[str]) → None: remove tags from a given tag group :param group: the tag group to remove tags from :param tags: a list of tags to remove

set(group: str, tags: List[str]) → None: replace all tags on the given tag group with these tags :param group: the tag group to set tags on :param tags: a list of tags to set

send() → Response

commit add, remove and set operations. set cannot be used with add and remove.

Returns:: the response object from the api

class urbanairship.devices.email.EmailAttachment(airship: BaseClient, filename: str, content_type: str, filepath: None | str = None, file_data: None | bytes = None)

Create an email attachment from a file. Please see https://docs.airship.com/api/ua/#operation/api/attachments/post for important information about file size, content type, and send type limitations.

Parameters:

filename – Required. The name of the uploaded file (max 255 UTF-8 bytes). Multiple files with the same name are allowed in separate requests.
content_type – Required: The mimetype of the uploaded file including the charset parameter, if needed.
filepath – Optional. A string path to the file to be uploaded and attached. File must have permissions set to be opened in ‘rb’ (binary) mode.
file_data – Optional. A string representation of the file to be uploaded and attached.

Returns:

the response object from the API including the ‘attachment_ids’ uuid to be used in the email override object.