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 unistall 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

class urbanairship.devices.sms.Sms(airship: BaseClient, sender: str, msisdn: str, opted_in: datetime | None = None, template_fields: Dict | None = None, locale_country: str | None = None, locale_language: str | None = None, timezone: str | None = None)

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.

  • 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

class urbanairship.devices.email.Email(airship: BaseClient, address: str, commercial_opted_in: str | None = None, commercial_opted_out: str | None = None, transactional_opted_in: str | None = None, transactional_opted_out: str | None = None, locale_country: str | None = None, locale_language: str | None = None, opt_in_mode: str | None = None, properties: Dict | None = None, timezone: str | None = None, template_fields: Dict | None = None)

Register and uninstall an Email object.

Please see the email documentation for important information about opt-in times and email types. hhttps://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: str)

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 – Required. A path to the file to be uploaded and attached. File must have permissions set to be opened in ‘rb’ (binary) mode.

Returns:

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