MobileCommons

Overview

MobileCommons is a broadcast text messaging tool that helps orgranizations mobilize supporters and fundraise by building opt-ed in audiences. You can read more about the product here.

Quick Start

To instantiate a class you must pass the username and password of a MobileCommons account as an argument or store the username and password into environmental variables called MOBILECOMMONS_USERNAME and MOBILECOMMONS_PASSWORD, respectively. If you MobileCommons account has access to various MobileCommons companies (i.e. organizations), you’ll need to specify which MobileCommons company you’d like to interact with by specifying the Company ID in the company_id parameter. To find the Company ID, navigate to the Company and Users page.

from parsons import MobileCommons

# Pass credentials via environmental variables for account has access to only one MobileCommons company
mc = MobileCommons()

 # Pass credentials via environmental variables for account has access to multiple MobileCommons companies
 mc = MobileCommons(company_id='EXAMPLE78363BOCA483954419EB70986A68888')

 # Pass credentials via argument for account has access to only one MobileCommons company
 mc = MobileCommons(username='octavia.b@scifi.net', password='badpassword123')

Then you can call various endpoints:

# Return all MobileCommons subscribers in a table
subscribers = get_campaign_subscribers(campaign_id=1234567)

# Create a new profile, return profile_id
new_profile=create_profile(phone=3073991987, first_name='Jane', last_name='Fonda')

API

class parsons.mobilecommons.mobilecommons.MobileCommons(api_key=None, company_id=None)[source]

Instantiate the MobileCommons class.

Parameters:

  • api_key – str A valid API Key created by a MobileCommons account. Not required if MOBILECOMMONS_PASSWORD env variable is set.

  • company_id – str The company id of the MobileCommons organization to connect to. Not required if API key is for an account associated with only one MobileCommons organization.

get_broadcasts(first_date=None, last_date=None, status=None, campaign_id=None, limit=None)[source]

A function for get broadcasts

Parameters:

  • first_date – str The date of the earliest possible broadcast you’d like returned. All common date format should work (e.g. mm/dd/yy or yyyy-mm-dd)

  • last_date – str The date of the latest possible broadcast you’d like returned. All common date format should work (e.g. mm/dd/yy or yyyy-mm-dd)

  • status – str ‘draft’, ‘scheduled’, or ‘generated’

  • campaign_id – int Specify to return broadcasts from a specific campaign

  • limit – int Max rows you want returned

Returns:

Parsons table with requested broadcasts

get_campaign_subscribers(campaign_id: int, first_date: str | None = None, last_date: str | None = None, opt_in_path_id: int | None = None, limit: int | None = None)[source]

A function for getting subscribers of a specified campaign

Parameters:

  • campaign_id – int The campaign for which you’d like to get subscribers. You can get this from the url of the campaign’s page after select a campaign at https://secure.mcommons.com/campaigns

  • first_date – str The date of the earliest possible subscription returned. All common date format should work (e.g. mm/dd/yy or yyyy-mm-dd)

  • last_date – str The date of the latest possible subscription you’d like returned. All common date format should work (e.g. mm/dd/yy or yyyy-mm-dd)

  • opt_in_path_id – int Optional parameter to narrow results to on particular opt-in path. You can get this from the url of the opt in paths page https://secure.mcommons.com/opt_in_paths

  • limit – int Max rows you want returned

Returns:

Parsons table with requested broadcasts

get_profiles(phones: list | None = None, first_date: str | None = None, last_date: str | None = None, include_custom_columns: bool = False, include_subscriptions: bool = False, limit: int | None = None)[source]

A function for getting profiles, which are MobileCommons people records

Parameters:

  • phones – list A list of phone numbers including country codes for which you want profiles returned MobileCommons claims to recognize most formats.

  • first_date – str The date of the earliest possible subscription returned. All common date format should work (e.g. mm/dd/yy or yyyy-mm-dd).

  • last_date – str The date of the latest possible subscription you’d like returned. All common date format should work (e.g. mm/dd/yy or yyyy-mm-dd).

  • include_custom_columns – bool Optional parameter to that, if set to True, will return custom column values for profiles as a list of dictionaries contained within a column.

  • include_subscriptions – bool Optional parameter to that, if set to True, will return a list of campaigns a given profile is subscribed to in a single column

  • limit – int Max rows you want returned

Returns:

Parsons table with requested broadcasts

create_profile(phone, first_name=None, last_name=None, zip=None, addressline1=None, addressline2=None, city=None, state=None, opt_in_path_id=None, custom_column_values=None)[source]

A function for creating or updating a single MobileCommons profile

Parameters:

  • phone – str Phone number to assign profile

  • first_name – str Profile first name

  • last_name – str Profile last name

  • zip – str Profile 5-digit postal code

  • addressline1 – str Profile address line 1

  • addressline2 – str Profile address line 2

  • city – str Profile city

  • state – str Profile state

  • opt_in_path_id – str ID of the opt-in path to send new profile through. This will determine the welcome text they receive.

  • custom_column_values – dict Dictionary with custom column names as keys and custom column values as dictionary values

Returns:

ID of created/updated profile