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: urbanairship.core.Airship)

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: urbanairship.core.Airship)

Uninstalls a channel id.

Parameters

airship – Required. An urbanairship.Airship instance

uninstall(channels: List[str]) → requests.models.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: urbanairship.core.Airship)

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() → requests.models.Response

Create this OpenChannel object with the API.

update() → requests.models.Response

Update this OpenChannel object.

classmethod from_payload(payload: Dict, airship: urbanairship.core.Airship)

Instantiate an OpenChannel from a payload.

lookup(channel_id: str)

Retrieves an open channel from the provided channel ID.

uninstall() → requests.models.Response

Mark this OpenChannel object uninstalled

SMS

class urbanairship.devices.sms.Sms(airship: urbanairship.core.Airship, sender: str, msisdn: str, opted_in: Optional[datetime.datetime] = None, template_fields: Optional[Dict] = None, locale_country: Optional[str] = None, locale_language: Optional[str] = None, timezone: Optional[str] = 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: Optional[datetime.datetime] = None) → requests.models.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: Optional[str] = None) → requests.models.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() → requests.models.Response

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

Returns

the response object from the api

uninstall() → requests.models.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() → requests.models.Response

Look up Sms channel information

Returns

the response object from the api

class urbanairship.devices.sms.KeywordInteraction(airship: urbanairship.core.Airship, keyword: str, msisdn: str, sender_ids: List[str], timestamp: Optional[datetime.datetime] = 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() → requests.models.Response

Send the interaction

class urbanairship.devices.sms.SmsCustomResponse(airship: urbanairship.core.Airship, mobile_originated_id: str, sms: Optional[Dict] = None, mms: Optional[Dict] = 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: urbanairship.core.Airship, address: str, commercial_opted_in: Optional[str] = None, commercial_opted_out: Optional[str] = None, transactional_opted_in: Optional[str] = None, transactional_opted_out: Optional[str] = None, locale_country: Optional[str] = None, locale_language: Optional[str] = None, opt_in_mode: Optional[str] = None, properties: Optional[Dict] = None, timezone: Optional[str] = None, template_fields: Optional[Dict] = 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() → requests.models.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: Optional[str] = None) → requests.models.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() → requests.models.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: urbanairship.core.Airship, 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() → requests.models.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: urbanairship.core.Airship, 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.